Simon Willison describes the Perfect Commit as a single commit that contains all of the following:
- The implementation: a single, focused change
- Tests that demonstrate the implementation works
- Updated documentation reflecting the change
- A link to an issue thread providing further context
Here’s four paragraphs on how he got to here:
I went through a several year phase of writing essays in my commit messages, trying to capture as much of the background context and thinking as possible.
My commit messages grew a lot shorter when I started bundling the updated documentation in the commit—since often much of the material I’d previously included in the commit message was now in that documentation instead.
As I extended my practice of writing issue threads, I found that they were a better place for most of this context than the commit messages themselves. They supported embedded media, were more discoverable and I could continue to extend them even after the commit had landed.
Today many of my commit messages are a single line summary and a link to an issue!