Meaningful commit messages

At Code Enigma, most of our Jenkins builds post a git log into one of our IRC channels on completion. This helps the ops team to keep an eye on what’s going on and to quickly spot any build failures. It also gives us a chance to see the commit messages that people are posting.

Our own developers are pretty well behaved when it comes to making meaningful commit messages (they know they’ll be teased mercilessly if they do anything daft!), but for some hosting-only clients, we have seen some classic examples of meaningless commit messages.

Here are some of the best (worst!):

  • no message
  • . (yes, just a dot!)
  • qwerty
  • fix?
  • kill me
  • [redacted] v1
  • [redacted] v2
  • [redacted] v3

I’m sure that everyone who has spent any time with git has come across their fair share of similar commit messages too.

At Code Enigma, I work as part of the support and ops team, so my observations here are more geared to that rather than individual development projects. If I’m going to be able to support your site, then being able to read a coherent narrative in your git log is a big help.

There are plenty of excellent posts on commit message best practice, such as http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html and http://who-t.blogspot.de/2009/12/on-commit-messages.html.

The longer commit messages described in those posts are great if you’ve been working in a feature branch, as you can squash all the individual commits into one big commit, complete with a comprehensive message, to be merged back into the main branch. Working this way makes it much easier if you need to revert the change further down the line. Rather than having to revert every individual commit referencing a ticket number, you just have the one commit to revert. Thanks to Chris for teaching me about git squashing!

For smaller commits, a huge commit message doesn’t make much sense. Think, though, what information would a sysadmin or support engineer find useful?

  • If you use a ticketing system, include the ticket number. If you use several ticketing systems, make it obvious which one the ticket reference is from.
  • Don’t describe the code itself, describe the reasoning behind the code changes. This is particularly important if you’re not using a ticketing system as I can’t track down the information anywhere else.
  • If you’re doing core/module updates, I don’t want to see a commit message of just “module updates”. That doesn’t tell me anything useful! Commit messages like “r1234 - Security update for addressfield_tokens, 7.x-1.4 to 7.x-1.5.” give me much more information and save me from having to dig into the code, saving you support time.
  • Another one that I see often is “Updating features”. Again, as a commit message, it’s practically useless. Here’s a much better example from one of our devs - “r6313: Exported [redacted] back to code from LIVE environment”. If I need to know more, I can check the code, but the commit message tells me what’s going on.
  • Only commit fixes for one issue at a time, unless they really are interlinked. If I’m working on a support problem, it’s a big help to be able to easily revert something as part of the debugging process without the risk of breaking something else.

There’s a well known saying, “Always code as if the developer who ends up maintaining your code will be a violent psychopath who knows where you live”. Instead of thinking of this as just applying to your code, think of it when writing your commit messages too!