A Note on Git Commit Messages

A team of engineers has to agree to certain rules everyone plays by to make the process as smooth as possible. You are being challenged with various problems that occur as soon as the team grows. Every engineer will bring their very own perspective - which is extremely beneficial.

Challenges closesly related to code are following SOLID principles, commenting code appropriately and sufficiently, writing meaningful commit messages and much more. In this post I want to highlight a few things to consider about meaningful commit messages.

While it’s perfectly fine to agree on “writing a commit message that explains roughly what the commit changes”, you will soon realise that it is not always that and also the problem relies a layer below already. One should be aware of the key factors that make a good commit: that is what changes are included at what stage, then following a meaningful message.

A specification named Conventional Commits suggests best practices for writing commit messages that are well perceived by humans but can also be grouped by machines for automated CHANGELOG generation. I highly suggest looking at the specification and maybe considering to implement it into your flow. You can also enforce the policy automagically using Git hooks.

The commit contains the following structural elements, to communicate intent to the consumers of your library:

  • fix: a commit of the type fix patches a bug in your codebase (this correlates with PATCH in semantic versioning).
  • feat: a commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in semantic versioning).
  • BREAKING CHANGE: a commit that has the text BREAKING CHANGE: at the beginning of its optional body or footer section introduces a breaking API change (correlating with MAJOR in semantic versioning). A BREAKING CHANGE can be part of commits of any type.
  • Others: commit types other than fix: and feat: are allowed, such as chore:, docs:, style:, refactor:, perf:, test:, and others.