Solving Problems, One Commit at a Time
If you have been following some of my projects in the past year or so, you might have noticed that the my commit messages changed considerably and they no longer look typical. Take a look at this one:
I shamelessly copied this commit message format from Pieter Hintjens’ C4 unprotocol. At first, this kind of commit message felt weird. Why would we want to begin every commit with a word “Problem”? What’s in it for me?
Turns out, there are multiple benefits to sticking to this ceremony.
Firstly, it gives you, the author of the change, an opportunity to understand what you are actually working on. Often times, if I am not quite sure what am I trying to accomplish, I’d prepare a WIP commit or a GitHub issue that simply and unambigously states the problem.
As opposed to purely self-documenting commit messages (say, “Added a reference to a user ID”) we’re documenting the reason why we bothered to torture the keyboard in the first place.
As a consequence, this kind of scoping prevents us from having to figure out the level of granularity of commit messages. A friend of mine recently complained to me that his new hire is pushing tons of very small commits and that was bothering him. As annoying as that may be, this case illuminates the underlying problem: where do we draw the line in the sand if our changes are, say, touching different parts of the system?
With this approach, we can draw that line at solving one and only one problem at a time.
Secondly, it gives you a context to every past change. Lets be frank, how easy is it for you to remember why you, let alone another person, did this or that change, three months later? A year? Ten?
By recording the entire context, we are giving everybody who’ll be working with the codebase (contributors, users, etc.) a way to figure out why changes happened in the first place. In some cases it would relieve frustration, in other, it’ll help figuring out which problems aren’t problems anymore and therefore, what kind of improvements can be made.
Thirdly, it’s a great way to understand incoming changes. If you maintained a collaboratively developed project before, how many times have you received a pull request that left you wondering “why on Earth?..”
By focusing on (and explicitly stating) the problem this change is solving, you can help the maintainers understand your perspective and (surprise, surprise!) make it easier for your change to be successfully merged.
Which leads me to another point. Not being able to understand each other is often the reason why people can be less than excellent to each other. This being a big issue in the community these days, working on contributing to a pool of shared meaning will be a net benefit.
I’ve heard some concerns about using this format, mostly boiling down to “my team mates aren’t producing insanely great commit messages right now, how can I expect them to adhere to a much more demanding format?”
On the surface, this makes sense. However, the beauty is in rigidity of this format. It gives you simple rules, a framework for making statements of a very specific kind. Once most of common mistakes are learned, this becomes a second nature. As far as I can tell, the most common issue is writing messages like “Problem: no author_id” / “Solution: add author_id”. Obviously, this is a problem expressed through the solution, so an extra step has to be made to understand why there is this change.
Try it out on an open source or a side-project!
Bonus tip: when starting a new project, make an empty first commit with the Problem/Solution statement in its message. This will help others understand WHY this project has been started and WHAT does it do.
If you enjoy my writing or my open source work, please considering becoming my patron on Patreon. Awesome rewards included! Visit https://www.patreon.com/yrashk
