Small commits and good commit messges

An important thing when using a tool like git bisect as well as reviewing pull/merge requests and commits is to have small (aka “atomic”) commits.

Commits with small changes make them easier to review and, if needed, to revert and debug with bisect. If a commit has ten new or changed lines, it’s much easier to see and fix a bug than if the commit had a hundred lines.

If you’re doing code reviews or “Showing” in a Ship/Show/Ask format, you’ll likely get better and more valuable feedback if the commits are smaller and only doing one thing.

If you’re submitting a change for review, commit a failing test first so that it can be seen failing before committing the code to make it pass. This makes it easier to see that the code is actually making the test pass.

Also take some time to write good, informative commit messages.

As well as the short one-line subject, you can add as much detail as you need to the body of the message about the change that’s being committed, why it’s needed, what other approaches were considered or tried, as well as links to supporting documentation such as ADRs, technical design documents or diagrams.

Having as much information as possible makes it much easier when someone needs to review or fix a specific commit. I like to use the conventional commits specification, though the main objective is to have all of the information documented so it’s available in the future.