The Perfect Commit  ↦

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!


Sign in or Join to comment or subscribe

  0:00 / 0:00