Over the years, I have been trying different ways of writing commit messages - And I now think that it’s best to write a present tense commit messages that describes the new capabilities of the system I am working on.
Let me explain…
When I am working for clients, I try to write commit messages in the same style that the team uses. But most teams I worked with in the past do not have guidlines or a team agreement - they do not even use a coherent style. They do not care about their commit messages. But they could benefit from writing more expressive commit messages.
Over the years, I have read some guides for writing better commit messages (I will link two good ones at the end) and I have experimented with writing more expressive commit messages in my own projects.
I have come to the conclusion that writing down the new capabilities in present tense works best for me:
Present-Tense, New Capabilities
I usually try to write commit messages so that they tell me how the software works now (and NOT what has changed or what I did), because then the messages are a nice history of the capabilities of my software.
Sometimes, that’s easy. This commit message is from a project I am working on right now. I wrote a React component that will show premium features only when the user is on a paid plan:
Shows upgrade hint when user does not have plan. The <Feature> component shows an upgrade hint when the user does not have the required paid plan to use a feature. This allows us to advertise paid plans and to add upgrade buttons to upgrade within the app.
Note how this message does not only include what the system can do now that it couldn’t do before the commit, but also why (advertising paid plans). Include the why in your commit messages so that future readers can better understand the reasons for the steps you took.
Purely Technical Changes
But sometimes it’s a little hard for me to find the right words, especially for purely technical changes or refactorings.
The hard part about writing commit messages for purely technical changes is that there are often no clearly-defined new capabilities. In this case, I sometimes fall back into writing a commit message about what I did, like:
Refactored state/reference pairs I exctracted a function to change arbitrary state/reference pairs to remove duplication in <EditView>.
The problem? The “capabilities” commit messages (like above) form a history of what the software system can do. Together, they form a story of how the software system grew over time. And now there is a commit that only says what I, the programmer, did. This is not some interesting information when we read the message later.
The new capability of the system, in this case, is that its code is easier to read for a human (less duplication) and that it is harder to make programming mistakes (the state and reference values always change together).
So, when I realize that I am falling back into my old behavior, I try to do better. Maybe that sounds a bit artificial, but it is more consistent:
Refactor better readability in <EditView> There are some pairs of state/reference in EditView that must be changed togehter. The code for changing those is now in a function so that one can change the values with a single function call, avoiding mistakes where one forgets to change one value after the other.
I try to use present tense to describe the new capabilities of the system in my commit message. Then, the commit messages together form a story of what the system could do at a certain point in time.
It’s relatively easy for me to come up with those commit messages for new features, a little harder for bugfixes and often quite hard for refactorings and purely technical changes. But I try anyway. Often, the new capability is that the code supports us - the software developers - better.
But it is also important to use commit messages consitently in a team. If your team never reads the commits again and so uses very short, non-descriptive commit messages, then write in their style. Maybe the commit messages are not interesting for you, for whatever reason.
But if they are interesting (or if they could be!), get together, have a retrospective, and talk about writing better commit messages. You might want to talk about my suggestions, but please also read other guides and find a style that works for your team: