Write a good commit message

Commit messages are one of the most common ways developers communicate with each other, so it’s important to clearly communicates any changes.

Typically, the audience of a commit message is:

• People reading the commit timeline.
• People debugging code.

Elements of a good commit message

1. Good commit messages should have a sentence in the subject line briefly describing what the change is and when appropriate, why it was necessary.

A good subject line gives the reader the power to know the gist of the commit without needing to read the entire commit message.

Example:

Fix stats link on m.example.com

This does not need a high-level why part, because it’s clear that the links weren’t working.

Example:

Status Report: clear caches on each post to save memory

We need a why part, because if the message was only “clear caches on each post”, the follow-up question would be, “Why would you clear cache for each post in a loop?”.

2. There should be an empty line between the subject line and the rest of the commit message (if any) for readability.

3. A good commit message should explain the reasoning behind why a change was made.

Those following the timeline can learn a new approach and those tracing bugs can understand the context of the problem better, which may help decide whether the root cause is in the implementation or further up the chain.

If the explanation for the change is obvious (e.g., “I’m fixing it because it’s broken”), go a level deeper. The 5 Whys technique can be helpful for ensuring you’re not only looking for root causes of problems, but also what you are doing is for the right reasons.

Example:

JSON API: Split class into hierarchy for easier inclusion in ExamplePlugin

Including the old code required a bunch of hacks and compatibility layers.
With the new hierarchy, we can get rid of almost all the hacks and drop the files into ExamplePlugin as is.

The commit message above explains what the downsides were of the old approach and why the new approach is preferable.

Example:

Remove filtering by ticket

It's not very useful, while it's slow to generate.

The workflow is to usually go to the ticket page and see associated
comments there.

This commit message shares a UX decision made, the primary reason of the commit.

5. Most commits fix a problem, but a good commit message explains what caused the problem and its consequences.

Knowing what caused a problem can avoid causing a similar problem again and understanding the consequences can help explain any erroneous behavior. For instance, during debugging, one can compare the consequences of a fixed problem with the new one.

6. A good commit message explains how it achieves its goal.

On occasions where it’s unclear, explaining the how benefits the reader (e.g. some high-level algorithm is encoded in the change) and highlights the importance of knowing it.

Example:

Add a first pass client stat for bandwidth

Bandwidth is extrapolated from a month sample. From
there we get the average number of bytes per pageview
for each blog. This data is cached in means.json.

All the code for generating the data in means.json is
in the static methods of the class.

Above, we explain the algorithm for guessing bandwidth data. This avoids requiring a future reader to use time and energy in extracting this information from the commit.

7. If the subject line of a commit message contains the word and or in other way lists more than one item, the commit is probably too large. Split it.

Make your commits as small as possible. If you notice a coding style problem (e.g. white space changes) or another bug while fixing a bug, make a note to fix it afterwards in a separate commit.

8. It’s perfectly OK to spend more time crafting your commit message than writing the code for your commit.

It’s possible that your commit message is longer than your commit and that’s fine. Common sense can overrule what we think a good commit message should be.

9. A good commit message gives props and references for more context.

10. References are not a substitution for explanations.

For example, a link to a 20-comments discussion without a clearly extracted conclusion creates potential confusion.