~6 min read|
In a recent sprint retrospective, a teammate mentioned that we could help ourselves by adding more context to our pull requests. This got me thinking and I started reading about how other teams handled this problem. This search led me to
three resources which are changing the way I’m thinking about commits:
Each of these blog posts and talks are worth investigating on their own and I highly encourage reading/watching them all! The purpose of this post is to call out a few of the lessons I took from them, but focusing primarily (at least for now) on Joel’s talk. Joel presented a three pronged framework for writing effective commits:
What do they mean?
Atomic commits are the “minimum viable commit.” It’s the smallest chunk of code that together means something. Here, the
--patch flag (also
git add is particularly useful. A heuristic to use: If you need to use “and” to describe the commit, it may be too big.
Meaningful commit messages are described in four parts:
Chris Beams’ article includes a sample commit that demonstrates all of this quite well
Summarize changes in around 50 characters or less More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. In some contexts, the first line is treated as the subject of the commit and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); various tools like `log`, `shortlog` and `rebase` can get confused if you run the two together. Explain the problem that this commit is solving. Focus on why you are making this change as opposed to how (the code explains that). Are there side effects or other unintuitive consequences of this change? Here's the place to explain them. Further paragraphs come after blank lines. - Bullet points are okay, too - Typically a hyphen or asterisk is used for the bullet, preceded by a single space, with blank lines in between, but conventions vary here If you use an issue tracker, put references to them at the bottom, like this: Resolves: #123 See also: #456, #789
I’ve ultimately settled on an approach similar to Chris’ with one significant departure: where to reference issues. Instead of placing them at the bottom, I like using some of the real-estate in the first line to note the issue. For example,
Summarize changes in around 50 characters or less [PROJ-123]
This is largely a product of the fact that I begin my investigation of git history by reading one-line summaries - and seeing the ticket number is useful.3
Ultimately, though, there are two side-effects to this approach that I find beneficial:
Revising history before sharing was probably the most eye opening for me. It was an argument for using
git rebase --interactive in a way to help organize commits to tell a story. If the point of the commit is to communicate to a future developer what happened and why, then eliminating noise of commits like
fix typo and
linting makes that easier.
While these are trivial examples, Joel provided really interesting ones - like reorganizing the order of commits and merging them to be more complete units (e.g., combining a change with the test case written to cover it rather than leaving those as two separate commits).
Before seeing these talks and reading these articles, I thought I was doing alright with my commits, but what David, Tekin, and Joel showed me was that there’s so much more I can do - not just to help myself, but to help my team.
It’s a little extra effort, but it seems to be appreciated. I get comments from my teammates that they find my commit messages helpful, which is really all I could hope for. More than that, though, Chris notes:
A project’s long-term success rests (among other things) on its maintainability, and a maintainer has few tools more powerful than his project’s log.
Spending a few minutes to master the tools and write useful commit messages feels well worth the opportunity to succeed over time. This is not gold-plating. Rather, it’s how projects survive and thrive.
glwhich creates a concise picture using the following formatting. For more on the alias, see my post, Git: Pretty One Line Logs.
Hi there and thanks for reading! My name's Stephen. I live in Chicago with my wife, Kate, and dog, Finn. Want more? See about and get in touch!