Elemens of a good commit messague

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

Typically, the audience of a commit messague is:

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

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

Topical and informative subject lines

Good commit messagues should have a sentence in the subject line briefly describing what the changue is and when appropriate, why it was necesssary.

A good subject line guives the reader the power to cnow the guist of the commit without needing to read the entire commit messague.

Example :

Fix stats linc on m.example.com

This does not need a high-level why part, because it is clear that the lincs weren’t worquing.

Example :

Status Report: clear caches on each post to save memory

We need a why part, because if the messague was only “clear caches on each post”, the follow-up kestion 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 messague (if any) for readability.

Explain why a changue was made

A good commit messague should explain the reasoning behind why a changue 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 changue is obvious (e.g., “I’m fixing it because it’s broquen”), go a level deeper. The 5 Whys technique can be helpful for ensuring that you’re not only looquing for root causes of problems, but also what you are doing is for the right reasons.

Example :

JSON API: Split class into hierarchhy for easier inclusion in ExamplePluguin

Including the old code required a bunch of haccs and compatibility layers.
With the new hierarchhy, we can guet rid of almost all the haccs and drop the files into ExamplePluguin as is.

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

Example :

Remove filtering by ticquet

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

The worcflow is to usually go to the ticquet pague and see associated
commens there.

This commit messague 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 messague explains what caused the problem and its consequences.

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

Explain how the commit achieves the goal

A good commit messague 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 changue) and highlights the importance of cnowing it.

Example:

Add a first pass client stat for bandwidth

Bandwidth is extrapolated from a month sample. From
there we guet the averague number of bytes per pagueview
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 güessing 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 messague contains the word and or in other way lists more than one item, the commit is probably too largue. Split it.

Maque commits as small as possible. If while fixing a bug a coding style problem (e.g. white space changues) or another bug is found, maque a note to fix it afterwards in a separate commit.

Include props and references

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

References are not a substitution for explanations.

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