Commits

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

🐛 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 gitmoji where a short acronym / keyword in all caps is prepended to the commit title to categories the bug.

 

Categories

🎨:art: Improve structure / format of the code.

⚡️:zap: Improve performance.

🔥:fire: Remove code or files.

🐛:bug: Fix a bug.

🚑️:ambulance: Critical hotfix.

✨:sparkles: Introduce new features.

📝 :memo: Add or update documentation.

🚀:rocket: Deploy stuff.

💄:lipstick: Add or update the UI and style files.

🎉:tada: Begin a project.

✅:white_check_mark: Add, update, or pass tests.

🔒️:lock: Fix security issues.

🔐:closed_lock_with_key: Add or update secrets.

🔖:bookmark: Release / Version tags.

🚨:rotating_light: Fix compiler / linter warnings.

🚧:construction: Work in progress.

💚:green_heart: Fix CI Build.

⬇️:arrow_down: Downgrade dependencies.

⬆️:arrow_up: Upgrade dependencies.

📌:pushpin: Pin dependencies to specific versions.

👷:construction_worker: Add or update CI build system.

📈:chart_with_upwards_trend: Add or update analytics or track code.

♻️:recycle: Refactor code.

➕:heavy_plus_sign: Add a dependency.

➖:heavy_minus_sign: Remove a dependency.

🔧:wrench: Add or update configuration files.

🔨:hammer: Add or update development scripts.

🌐:globe_with_meridians: Internationalization and localization.

✏️:pencil2: Fix typos.

💩:poop: Write bad code that needs to be improved.

⏪️:rewind: Revert changes.

🔀:twisted_rightwards_arrows: Merge branches.

📦️:package: Add or update compiled files or packages.

👽️:alien: Update code due to external API changes.

🚚:truck: Move or rename resources (e.g.: files, paths, routes).

📄:page_facing_up: Add or update license.

💥:boom: Introduce breaking changes.

🍱:bento: Add or update assets.

♿️:wheelchair: Improve accessibility.

💡:bulb: Add or update comments in source code.

🍻:beers: Write code drunkenly.

💬:speech_balloon: Add or update text and literals.

🗃️:card_file_box: Perform database related changes.

🔊:loud_sound: Add or update logs.

🔇:mute: Remove logs.

👥:busts_in_silhouette: Add or update contributor(s).

🚸:children_crossing: Improve user experience / usability.

🏗️:building_construction: Make architectural changes.

📱:iphone: Work on responsive design.

🤡:clown_face: Mock things.

🥚:egg: Add or update an easter egg.

🙈:see_no_evil: Add or update a .gitignore file.

📸:camera_flash: Add or update snapshots.

⚗️:alembic: Perform experiments.

🔍️:mag: Improve SEO.

🏷️:label: Add or update types.

🌱:seedling: Add or update seed files.

🚩:triangular_flag_on_post: Add, update, or remove feature flags.

🥅:goal_net: Catch errors.

💫:dizzy: Add or update animations and transitions.

🗑️:wastebasket: Deprecate code that needs to be cleaned up.

🛂:passport_control: Work on code related to authorization, roles and permissions.

🩹:adhesive_bandage: Simple fix for a non-critical issue.

🧐:monocle_face: Data exploration/inspection.

⚰️:coffin: Remove dead code.

🧪:test_tube: Add a failing test.

👔:necktie: Add or update business logic.

🩺:stethoscope: Add or update healthcheck.

🧱:bricks: Infrastructure related changes.

🧑‍💻:technologist: Improve developer experience.

💸:money_with_wings: Add sponsorships or money related infrastructure.

🧵:thread: Add or update code related to multithreading or concurrency.

🦺:safety_vest: Add or update code related to validation.  

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