Skip to content

Commits

Jump to bottom
John Pocock edited this page May 30, 2022 · 3 revisions

Try to follow these guidelines when writing commit messages. By following the guidelines our commits will be consistent and easy to work with.

Be Concise

Aim to be clear, concise, descriptive, and precise.

Aim to have your title be 50 characters of less where possible. This makes it display well in git command line tools and on GitHub etc.

Example

BUG: Calculate region coordinates at level 0

Separate the Title & Body With a Blank Line

Commit messages assume that the first line is the title. The body should therefore be separated by a blank line. Use the body of the commit to include more information, but only if needed. It does not need to be an essay but should be descriptive enough to explain the changes.

Example

BUG: Calculate region coordinates at level 0

Fix a bug in the calculation of coordinates when reading regions via OpenSlide during the utils.generate_tiles function. The (x, y) coordinates of a region should be calculated in terms of level 0 rather than the level which the region is being read at.

Use the Imperative Mood

When writing a commit the imperative mood should be used, e.g. "Fix bug" instead of "Fixes bug" or "Fixed bug". As a result, when reading back commits in the log it is clear what action is performed by each commit as it is applied.

Using the imperative also matches up with git verbs e.g. commit, fetch, pull, push, merge, cherry-pick etc. making the language describing what is being done more clear.

Additionally, avoid the use of personal pronouns e.g. "Fix bug..." instead of "I fixed a bug...".

Examples

Fix bug in feature

Add feature

Change feature to do something in a different way

Update README.md

 

Use a Prefix in the Title to Categorise the Commit

We are using a similar style to NumPy where a short acronym / keyword in all caps is prepended to the commit title to categories the bug.

 

Categories

API: An (incompatible) API change
BENCH: Changes to the benchmark suite
BLD: Change related to building tiatoolbox
BUG: Bug fix
DEP: Deprecate something, or remove a deprecated object
DEV: Development tool or utility
DOC: Documentation
NEW: New feature being introduced
ENH: Enhancement to an existing feature
MAINT: Maintenance commit (refactoring, typos, etc.)
REV: Revert an earlier commit
STY: Style fix (whitespace, PEP8, black)
TST: Addition or modification of tests
REL: Related to releasing tiatoolbox
EG: Adding examples e.g. notebooks
WIP: Work in progress

 

Manually Wrap Lines In The Body

Remember to add a line break at or before your message body reaches 72 characters. Many git tools with not auto wrap line and adding them in manually will make the messages display properly later.

Check For Typos: Especially in Titles

Typos are easily done. Please make a mental (or actual) checklist item to check for typos, particularly in title. If you do spot a mistake, you can always correct it via `git rebase -i` before pushing to your fork or making a pull request.

Capitalise the Title

Make sure to start the title line with a capital letter. Think of it like writing an email subject line.

Do Not Add a Full Stop to the End of the Title

Simple.

Reference Resolved Issues Via Their Number

Including the issue number makes it clear what issue this commit relates to. Additionally, GitHub will detect this and automatically link to the issue when viewed online.

Example

BUG: Calculate region coordinates at level 0

Fix a bug in the calculation of coordinates when reading regions via OpenSlide during the utils.generate_tiles function. The (x, y) coordinates of a region should be calculated in terms of level 0 rather than the level which the region is being read at.

Resolves issue #123.

Set Up Pre-Commit

The pre-commit package is in the requirements dev files and should already be installed if you have set up an environment. Otherwise you can install via pip, conda, homebrew etc.

Simply run

$ pre-commit install

  once within the repo after cloning to enable pre-commit hooks. This will format and check your code for you before you commit using black and flake8.

You can manually trigger the checks without committing your changes after you have staged files (git add) by running

$ pre-commit run

Ignoring Pre-Commit Errors

Note that you can skip the checks for a particular commit if you really need to (e.g. if you want to commit just part of a file and another part is causing the check to fail). See https://pre-commit.com/#temporarily-disabling-hooks for more.

If you simply want to make a commit and ignore any pre-commit errors, you can use the --no-verify option:

$ git commit --no-verify
Clone this wiki locally