February 05, 2020
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:
Joel Chippindale’s talk, “Telling stories through your commits,” presented a three pronged framework for writing effective commits which I intend to use as a bit of a checklist for the near future:
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:
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 happend 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).
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.
There are things I can start doing today that will help me and my team be more productive that cost me very little.
Thanks for reading! My name's Stephen Weiss. I live in Chicago with my wife, Kate, and dog, Finn.
Click here to see the archives of my weeks in review and sign up yourself!