Commit messages are user experience for developers. Both for other developers active right now and for developers (including ourselves) days/years/months from now. Think about the last time you were looking at a piece of code and asked yourself “Why is this here”. This is for you, this is your experience. I shared my four rules of thumb for commit messages, this is a little more in-depth.
Caleb Thompson proposes three questions that all commit messages should answer:
-
Why is this change necessary?
-
How does it address the issue?
-
What side effects does this change have?
In general, the first and second is the easiest to answer. In many cases, a link to your bug tracker will suffice (at least in part) for the first question. Your bug tracker should already contain the *why* for every change requested. The second question is important when the solution is complex.
Does this mean that all commit messages need to be bland? Absolutely not. WORLD WAR Z-INDEX: Restoration of sanity to revisions/slider/menu z-index values. is an excellent example of a commit message that is both fun and informative. The changeset is small ( 3 lines changed, 4 deleted), and is fairly easy for us to answer the question “What is changed?”. The why is answered with both a link to the ticket of
Erlang/OTP identifies three important purposes that commit messages serve:
Good commit messages serve at least three important purposes:
- To speed up the reviewing process.
- To help us write a good release note.
- To help the future maintainers of Erlang/OTP (it could be you!), say five years into the future, to find out why a particular change was made to the code or why a specific feature was added.
The third reason to me is likely the most important. Boone Gorges identifies blaming and annotation to be important tools in understanding the history of code and history of decisions in his talk Building a Better WordPress through Software Archaeology. Our software has a history and commit messages are the first draft of that history.
Further reading:
Commit Often, Perfect Later, Publish Once: Git Best Practices
Best Practices vary from environment to environment, and there is no One True Answer, but still, this represents a consensus from #git and in some cases helps you frame the discussion for the generation of your very own best practices.
Any software project is a collaborative project. It has at least two developers, the original developer and the original developer a few weeks or months later when the train of thought has long left the station. This later self needs to reestablish the context of a particular piece of code each time a new bug occurs or a new feature needs to be implemented.
5 Useful Tips For A Better Commit Message
Having a story in your git log will make a huge difference in how you and others perceive your project. By taking great care in commit messages, as you do in your code, you will help to increase overall quality.
Think of the commit log as a newsfeed for your project, in which the log message is the headline for each commit. Have you ever skimmed the headlines in a newspaper (or, for a more current example, BuzzFeed) and come away thinking you’d gotten a summary of what was happening in the world? A good headline doesn’t have to tell the whole story, but it should tell you enough to know what the story is about before you read it.