Elements of a good commit message

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

Typically, the audience of a commit message is:

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

It is perfectly acceptable to spend more time crafting a commit message than writing the code for a commit. It is possible that the length of the commit message is longer than the commit itself. Common sense can overrule what most people think a good commit message should be. A well written commit message can save time and work in the long run by clearly communicating the intention of the commit.

Topical and informative subject lines

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 is 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?”.

Spacing

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

Explain why a change was made

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 that 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.

Explain the problem’s cause and consequences

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.

Explain how the commit achieves the goal

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.

Reduce complexity

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 commits as small as possible. If while fixing a bug a coding style problem (e.g. white space changes) or another bug is found, make a note to fix it afterwards in a separate commit.

Include props and references

A good commit message gives props (i.e. “proper respects”) and references for more context.

References are not a substitution for explanations.

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