High-quality commits

Getting in the habit of crafting high-quality commits makes the use and collaboration with revision control systems such as Git a lot easier and more effective. Good commits help us:

1. Find out why a change was made.
2. Understand the different trade-offs that were made when implementing a change.
3. Locate when a given piece of code was changed and what else changed alongside it.
4. Revert or cherry-pick isolated changes we want to undo or apply onto another branch.

In addition, proper commit message summaries assist in quickly scanning a list of commits when looking for a specific change, building a mental context of what changed between any two given points in time, or when selecting commits during an interactive rebase.

Guidelines to creating high-quality commits

1. Break unrelated changes up into separate commits, don’t mix multiple unrelated changes together.
2. Don’t mix auto-formatting or whitespace changes with code changes. Commit them separately.
3. Use a descriptive title to summarize what changed. Try to name the outcome that is achieved instead of what was changed or how, as that can be understood from the body and the actual code diff.
4. Use the present tense and imperative mood (“Add feature” and “Fix ..”, not “Added feature”, “Fixed ..” or “Fixes ..”). You can check for this by mentally prefixing the phrase “If applied, this commit will ..” to your title.
5. Capitalize the subject line and do not end with a period.
6. Separate the title from the body with a blank line.
7. Avoid issue numbers or other markers in the subject line (place them within the body instead).
8. Wrap text at around 72 characters.
9. Use the body to explain what was changed (unless the diff is only a handful of lines), and most importantly why it was changed.
10. Go into detail on trade-offs or different implementations which were considered. Why was this specific implementation chosen?
11. Reference related issues, pull requests and other links in the body of the commit message.
12. Avoid markdown and assume readers will view it as plain text. Many tools won’t render markdown or other formatting.

An example commit message following these guidelines

Capitalized, short (50 characters or less) summary

More detailed explanatory text comes next, wrapped to 72 characters.
In some contexts, the first line is treated as the subject of the
commit and the rest of the text as the body. The blank line
separating the summary from the body is critical (unless you omit
the body entirely); various tools like "log", "shortlog" and "rebase"
can get confused if you run the two together.

Write your commit message in the imperative: "Fix bug" and not "Fixed bug"
or "Fixes bug."  This convention matches up with commit messages generated
by commands like git merge and git revert.

Explain the problem that this commit is solving. Focus on why you are
making this change as opposed to how (the code explains that). Are there
side effects or other unintuitive consequences of this change? How does
this change affect end-users? If it introduces breaking changes, how
should people deal with those?

- Bullet points are okay, too;

- Typically a hyphen or asterisk is used for the bullet, preceded
  by a single space, with blank lines in between, but conventions
  vary here.

Links to external references, tickets in issue trackers, etc. are
incredibly helpful. If you're incorporating links into the body of
the description, it's generally most readable when you number these
and provide them at the end, like so:

This example is based on the example from the Git book [1], which in
turn is based on Tim Pope's "A Note About Git Commit Messages" [2].

[1]: https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines
[2]: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

References