House styles for commit messages

Author: Lee Aplin

At Substrakt we’ve worked hard to develop good working practices that allow us to develop efficiently, and communicate with one another clearly.

When you work in a team of more than a couple of people, having procedures in place makes development a lot more streamlined. If you’re used to working alone it’s easy to forget how challenging it can be for a new developer to get up to speed with code written by someone else, and it can be equally difficult to decipher a git log without well-written commit messages.

We’ve taken onboard advice from other excellent articles about crafting a good commit message and tweaked these guidelines to suit our workflow.

The most important addition is the use of keywords to prefix commit message titles. Having an easily readable, concise commit message is important, especially if you’re hunting for a particular moment in time in the git logs, so we’ve found that adding the following prefixes forces us to write our messages in a useful style.

It’s worth noting that we only use the keywords in the commit titles, not the body, which is reserved for commits which require longer explanations. We also use uppercase for the keywords so that they are easily distinguishable when scanning the git log.

ADD: This one is straightforward. You added something to the codebase that wasn’t previously there. It indicates a new feature or a new block of code.

UPDATE: Refactoring existing code, updating a function to perform in a slightly different way, changing things after a code review. They all fall under the act of updating something.

REMOVE: Another easy one. You removed a piece of code, an unused library or a plugin that you don’t need anymore.

FIX: This one isn’t too different from UPDATE but signifies that you fixed a previously broken function or piece of code. It is useful to use the FIX prefix here instead of just UPDATE because in the logs you can easily find the moment when something that wasn’t working as expected was repaired. This helps you to track the progression of a project, as well as highlight to team members where you have adjusted something that they had may previously worked on.

There is a distinct benefit to using these keywords. Crucially, it helps you to think about what you just did instead of writing something too verbose. If you can categorise your work into one of these keywords, it is easy for someone else to understand what you did.

As an addition to these keywords, we avoid using the word ‘and’ in commit messages. If your commit message reads “UPDATE: Event query to exclude sticky posts and update blog templates”, then you’ve included two separate changes in one commit. It would have been better to split these up into two commits:

“UPDATE: Event query to exclude sticky posts”
“UPDATE: Blog templates”

This keeps your commits focused on one feature at a time and prevents large blocks of code being lumped together into unwieldy commits.

Overall its fairly straightforward stuff, but having everyone in a team on the same page really helps to prevent headaches when you’re reviewing an older project several weeks or months down the line.