In Red Meat Friday: Commit Messages Don’t Matter, the author references Matt Rickard’s post Commit Messages Don’t Matter. Below is the Irreal quote:
Matt Rickard makes the case that commit messages don’t matter and that our time is better spent elsewhere. My personal policy is to give a hint as to what the commit does and leave the details to diff or other appropriate commands. Once you get out of code police mode, it’s pretty clear that Rickard is right. But, of course, none of us want to get condemned for apostasy so we pretend to agree with the received wisdom.
On the surface, I disagree with the above.
Commit messages do matter; they are your opportunity to create one more artifact for the future archaeological efforts of reconstructing context. Your chance to say the why, to paraphrase the what, and to connect to prior work.
Let’s dig in to where I agree and build out from there.
From Matt Rickard: “pull requests are the de facto reviewable unit and workflows should probably be designed around them.”
The above alludes to an assumption of pull request via something like GitHub. But to generalize, let’s talk about them as change sets. The conversation around the change set is critical
The change set is what we are accepting into the code base. I like to think of the commit message as the cover letter for that change.
My personal philosophy of commit messages is to include the following:
- Short descriptive title.
- A statement of why the change.
- References to issues or other changes.
- Optionally a before and after description.
- Optionally the exception/call trace this commit addresses.
I then use that message to populate the pull request’s initial message. I wrote about that in Adding Emacs Function for my Forem Pull Requests. Ideally, once we merge the change set, we’ll also have a reference to the pull request as part of the commit. At a minimum we have the Secure Hash Algorithm (SHA 📖) and can look that up. If you use GitHub’s squash and merge strategy, it will append the pull request number to the commit.
The goal in all of the above is to provide way finding for those reviewing code as well as those later trying to understand context. Those references are an effort to connect into the potential “knowledge graph” that is being built through the development of the software.
All of this follows the principle in software development that you will likely spend more time reading than writing.