Bradley Kirton's Blog

Published on April 16, 2024

Go home

The anatomy of a good commit message

In this post I put forward some ideas on using conventional commit and structuring commit messages in order to extract useful information from commit data.

Conventional commit is a specification for adding human and machine readable meaning to commit messages. The full specification can be read here. The structure of a conventional commit is very simple.

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

I recommend choosing a set of types that make practical sense for your team. For example fix, feat, docs, chore, ci and refactor will probably cover most of your needs.

In addition to this, if you are using a ticketing system I strongly recommend including the information which links the ticket you are working on to the commit which implements it.

For example, suppose you are working on a ticket to fix an N+1 problem in a django view.

fix: DJ-001 nplus query optimisation

Refs: https://ticketing.system/tickets/DJ-001/