Why commit messages matter

A few months ago we published git commit message guidelines at our company. The defined rules are quite the same as the guidelines from Chris Beams. Before this step every development team had its own commit message “standard” and it was hard for developers to lookup some details inside the code base of another team. Almost every team only used one line commits and a few devs used ticket numbers as prefix of the commit message.

Writing good commit messages

A commit message should be written in a simple understandable language. It should be splitted into two parts, a subject line and a message body that can contain multiple lines.

Both the subject and the body should be written in imperative mood. Without this rule you will get this weird mix of tenses and when forming the message in imperative mood you get a quick feeling if the message sounds understandable.

The Subject

The subject of a commit message should start with a capital letter, should be short and (of course) should be informative. The length should be 50 characters at max. It has to provide a summary of the changes made in this commit. To have some sort of guidance you should try to complete the following sentence: “If applied, this commit will …”.

The Body

Inside the body the developer describes why the changes were made and what this changes are for. The “How” question must not be included because this question gets answered in the actual source code of the commit.

The other rules by Chris Beams are actually only syntactic sugar and best practices that should be applied also.

Gaining value from good commit messages

A developer may argue that the required detail of information is weird or not necessary because they implemented the feature and have detailed knowledge of the commits content. But for others the situation may be different and also for later use the commit message should give good information about the made changes.

I often had first-hand experience on the need of a good commit log when looking at a piece of source code that was written years ago and a particular change was made by someone. By executing git blame I often found messages “this should be removed…” or “temporary bugfix” or even “yadda yadda” … This type of message is not helpful at all, so you should convince yourself and your colleagues to follow the commit message guidelines.

Ticketing system != git log

A often mentioned point is, that the commit message body is unnecessary because a ticket reference is included in the subject and the linked ticket contains all information needed to understand the commit.

That is maybe true but for me a ticketing system is for specifying a business case or filing a bug report and must not contain a complete architectural picture of a feature to implement.

Programming is an art, it should involve some logical thinking and should leave the developer with (at least) some freedom to construct a good solution for a problem.

Another problem is the ticket number prefix or suffix in the subject line. It does not provide an overvalue. On the contrary it steals space for good and helpful information

Here is an example with the ticket number prefix:

TICKET-1234 add missing info to class

This structure should be avoided and the ticket number included as a reference in the body of the message:

Add missing meta fields to response

in addition to the title and the text the status and created
columns are added to the response to be able to filter content
by status and date in the FE

See: TICKET-1234

Enforcing the guidelines

The defined ruleset by Chris Beams contains very strict rules that may appeal fussy to developers. But as I learned from the past it is necessary to establish such rules to be confident that every repository contains the same sort of log information. that is helpful for anybody looking at the code base at some point in time.

To be able to monitor the quality of commit messages I wrote a simple Git webhook that gets triggered for every commit on push. All structural rules that can be validated by code are covered by the webhook. If the hook finds a violation the developer who did the commit gets noticed via a private slack message.

This automatism has resulted in a very good commit message quality. Now the webhook only sends out about 1 message a day.