Writing Commit Messages First
Writing your commit message first creates a local sense of stability analogous to working from “stories” off a backlog or trying to get the next failing test to pass. If you or your pair get lost in the weeds, pointing back to the story provides a direct and egoless way of getting back on track. Similarly, test driven development helps pairs stay focused by forcing incremental, falsifiable functionality. Writing your commit messages first keeps you and your pair focused between the feature you are currently trying to implement and whatever current change you are making that could be a smaller, more atomic pushable commit. So what does this look like?
You can use a command line tool to keep track of your commit messages or simply use pencil and paper. We’ll be using a stack for the data structure for how we will conceptually track these commit messages. The first commit message is easy and provides a frictionless start. A lot of thought usually goes into the title or description of a story and it provides the perfect level of abstraction to communicate the overall “why” for the actual changes needed to delivery the feature. Write down the commit message before changing any code and work from the assumption that all necessary changes will be committed with this message. When you come across a piece of code that for example needs structural changes to make your feature possible, stash or delete your current changes. Write down the commit message that describes the change you wish was already present so that you can “make the change easy… then make the easy change”. The new commit message is causally related to the original feature in the sense that by simply working on the original feature, we naturally discovered the smaller commit.
You can recursively repeat this process with the new subgoal as your focus until you arrive at work that you can finally commit (and push) using the message you’ve already written. Unwind to the next recorded commit message as the next thing you should focus on until you arrive at delivering the original feature, but now with the necessary minimal changes needed to deliver the feature.
Conceptually, I’ve articulated a slimmed down version of the “Mikado Method” but what I’d like to convey are the affordances of writing your commit messages first. At any moment, you or your pair can take a step back and ask “why” your changes are relevant by looking at the previous commit message, and “what” is needed from the current commit message. It keeps you and your pair accountable. Do the current changes really reflect the commit message that was written? When we write our commit messages after our changes, we often mix in work that isn’t relevant to the commit message or we begin to find it difficult to describe our changes. When we write our commit messages first, our commits become smaller and more cohesive and team integration becomes easier. Give it a try and let me know what kind of affordances you and your pair experience.
