You might assume that at the heart of software lies code, but as I argued here last year, I think it’s something else: change. After all, everything we do as developers can be boiled down to creating some kind of change. And the software components that most of us work with are changes, not files. If that’s true, perhaps the most important things we do as software engineers are crafting independent changes and writing clear, illuminating commit messages.
Commit messages are where we explain the changes we’ve made and why we made them. Done right, they both encourage and enable well-factored, incremental changes that ensure a project makes real and sustainable progress. This is even more important in open source engineering, where teams are radically distributed and people are often unknown to each other in real life.
In my experience, though, the link between commit messages and the commits they explain is sorely underappreciated. A few years ago, Chris Beams wrote a well-known blog post on “How to Write a Git Commit Message.” Beams came up with seven rules for doing it right:
- Separate subject from body with a blank line
- Limit the subject line to 50 characters
- Capitalize the subject line
- Do not end the subject line with a period
- Use the imperative mood in the subject line
- Wrap the body at 72 characters
- Use the body to explain what and why vs. how
The first six rules detail a set of practical guidelines that really do help make commit messages easier to read and understand. For me, though, the key rule is the seventh and last: “Use the body to explain what and why vs. how.” This is crucial information about the developer’s line of thinking. It includes what error message was seen, what the environment was, what the reproducing case is, why the approach to the solution was chosen and, lastly, what that solution actually is.
With all of that information, I can do my job as a reviewer better. I can look at the change submitted and decide whether the developer did indeed address the issue as intended and as actually needed. Later down the road when someone finds their machine crashing with an error message, they can Google that error message and see it in the git log together with the commit containing the fix to the error they’ve just encountered.
Does this mean your commits will end up like novels? Actually, it’s the opposite. While your metadata should be comprehensive, each commit itself should be as small and as independent as possible, while still remaining functional.
As developers, it’s really easy to get engrossed in the details of any change we are making. But we need to realize that there’s a lot more going on – both outside what we are contributing to and in the processes that follow from the changes we make.
Especially in large open source projects, there are hundreds – if not thousands – of changes being made at the exact same time. We can’t possibly know the potential global impact of our changes. With that said, good commit etiquette is about more than just describing what you are up to. It’s about making sure you develop your changes so that they are compatible with the broader set of changes happening around you.
After all, when you make changes, they are going to be used by your continuous integration team, your quality assurance team, your validation and verification teams. The release process decides which changes are going to be incorporated into a given release and which are going to be backported to an older release that is stable. For that reason, you want every change you make to be as small and as independent as possible. It gives your colleagues the greatest flexibility to build releases, fix bugs and backport as they need. It also allows your project to scale past you.
I’ll close with a few bonus tips for writing better commits:
- Remember your audience
When it comes to your commit message, always remember that someone should be able to read it and know exactly why you are making the change. It should justify every change in the code that you are creating.
- Remember where your colleagues work
In open source, commits should be clear of data related to your place of work. The person you will be justifying your changes to will most likely not work where you do. They don’t care about your timelines, deadlines or the urgencies of your product releases—they care instead whether this is a good change for the project. Therefore, you need to convey what was needed, what was fixed and suggest the next course of action.
- Try to be the low hanging fruit
If you make it hard to understand what you meant to do, you’ll get bumped to the bottom of the review stack. Make your reviewers’ life as easy as possible—do one thing per commit and document what you’ve done so that your changes will be easy to approve.
For more best practices around contributing to open source projects, stay tuned to the Open Source Blog and follow us on Twitter (@vmwopensource).
