How to write better commit messages

Lolcat

Commit messages are an important part of how software is developed, debugged and maintained, and when done badly can become an unnecessary barrier to collaboration in open source projects.

Bad commit messages make it harder to figure out where problems have been introduced, especially for newcomers to a project.

The worst-case scenario for anyone trying to make sense of changes to a project is a commit message that offers basically no information for a major change affecting multiple locations in the code.

"Message: Fixed It. Files: 1366 modified"
“Worst commit message ever” via Jeff Dallien

 

To get a good sense of how commit messages are useful, take a project and look at its history in the revision system. You’ll see something like this:

  • Revision 1525597: Add ap_errorlog_provider to make ErrorLog logging modular. Move syslog support from core to new mod_syslog.
  • Revision 1514267: tweak syntax strings for ServerTokens
  • Revision 1514255: follow-up to r813376: finish reverting r808965 (ServerTokens set foo)
  • Revision 1506474: server/core.c (set_document_root): Improve error message for inaccessible docroot.
  • Revision 1498880: Replace pre_htaccess hook with more flexible open_htaccess hook

Or, if you’re unlucky, you might see something like this:

  • Revision 1525597: fixed it
  • Revision 1514267: more changes
  • Revision 1514255: bug fixes
  • Revision 1506474: more improvements
  • Revision 1498880: lots of changes

If you now imagine you’re looking to find out where, say, the ServerTokens syntax changed, you can see the value of providing good commit messages.

So, how can you write better commit messages? Below are some top tips.

Be brief

Commit messages should be brief and easy to scan. Often the reader of commit messages is viewing then in a log or revision history, so make sure the most important words and phrases stand out.

There is no hard rule about this. Some developers prefer an approach of having a very short one-line message but with optional subsequent paragraphs of context and description, whereas others prefer to only provide one line of any length, and link to detailed explanations elsewhere, such as in the issue tracker.

However, you should use your common sense as to how much information should be in the commit message. If you find you’re writing lots of explanatory text, maybe you need to put more comments in the code itself where the changes are made, or add more detail to an issue in the tracker.

Make messages easier to find when searching

As well as scanning the revision history, developers also search logs using grep or similar tools. In which case its important to use the best terms for discovery. For example, if you use component or module names, make sure you spell them correctly and use them consistently. For example, if its a component called “DownloadManager” don’t use “Download Manager”.

Commit messages can also turn up in search engines, either project-specific searches or in regular web search engines. So its important to be clear and consistent in language use.

Provide sufficient context

While brevity is  desirable, commit messages need sufficient context to be useful.

For a one-line fix, you can always view the diff to see what changed, but if a commit affects multiple files or multiple lines of code, it needs more explanation so that other developers and users can re-establish the context of the commit.

Peter Hutterer suggests a commit message needs to answer three questions:

  • Why is it necessary? It may fix a bug, it may add a feature, it may improve performance, reliabilty, stability, or just be a change for the sake of correctness.
  • How does it address the issue? For short obvious patches this part can be omitted, but it should be a high level description of what the approach was.
  • What effects does the patch have? (In addition to the obvious ones, this may include benchmarks, side effects, etc.)

You don’t need to go into a lot of depth, but you need to capture enough of what is going on that someone reading the revision history can get a sense of what your commit did without having to look at all the diffs.

Added unicode support for imported files to prevent encoding errors in article.title

This doesn’t necessarily need to be in the message itself – for example, if there has been a  discussion on the mailing list, or there is plenty of information in a related issue on the project tracker, then you can include a reference or link to this in the commit message.

Added unicode support for imported files to prevent encoding errors in article.title (see bug #1345)

Some issue trackers can also link commits to an issue automatically based on the commit message, in which case you need to make sure you’re using the correct format for it to pick this up.

Provide credit and recognition where it is due

While you may be committing the changes, you may not in fact be the author – if you’re applying someone else’s changes, you need to acknowledge the fact and give the author recognition. Even if its not a complete submitted patch, but just a “if you change x to y that would fix the bug”, its worth putting in an acknowledgement.

Added unicode support for imported files to prevent encoding errors in article.title (see bug #1345). Thanks to Jane Doe for the patch

This has both a social function (placing credit where it is due) and also provides an audit trail.

(Some projects prefer a more formal “Submitted by: <username>” but I like to just say “thanks to <username>”.)

 Avoid repetition

Troy Hunt provides another rule of thumb for commit messages:  subsequent commit messages from the same author should never be identical.

This is partly because it makes it more difficult to distinguish changes in the version history, and partly because each change should, logically, be different to the last.

Try not to swear or insult anyone

Fixed stupid $$&!! mistake caused by £$%$%@ Steve

OK, it is difficult sometimes, but lets keep things professional. Save your venting for the IRC channel 🙂

More seriously, commit messages form part of the overall tone of communications for a project; snarky, rude and unhelpful commit messages don’t put your community in a good light, particularly for newcomers.

Check the logs to see how you’re doing

Every now and again its worth checking your log or revision history for your project, and reviewing the last page or so of commit messages. Would somehow relatively new to the project get a good idea of what was happening? Can you improve the usefulness of the messages that you and your community members are writing?

Follow project guidelines

Your project might have a preferred fromat for commit messages, so make sure you find out before making a commit.

For example, Moodle’s commit message guidelines call for a message subject line consisting of the issue number followed by component name, and the rest of the subject up to 72 characters.

Any more?

I’d love to hear any more suggestions for better commit messages (or your worst examples of bad practice!)

For a random commit message,  give WhatTheCommit a whirl

Photo credit: Wilson Afonso