PRs, Commits, and Code Reviews

Published at 2026-02-17 16:32:54 -0800

This is a post I wrote while I was at zendesk that I thought would be good to share with the world. This is a conversation that I had to have over and over and over again while reviewing PRs that were switched from draft to non-draft, which is why I eventually wrote this up:

PRs, Commits, and Code Reviews

Developers, Reviewers, lend me your ears!

When you’re authoring or reviewing a PR, please remember that the commit history is just as important as what’s inside the PR. Each commit should represent a meaningful and hopefully complete unit of change. The commit message should start with a one sentence summary of the change (the “what” AND the “why” of it) and be followed by any extra details describing context needed for understanding the unit of change.

To be clear, I’m NOT talking about draft PRs. I’m talking about code that you intend to get into the codebase, that is up for review, and that someone could merge at any time.

Authors: PRs and commits need to be well formed. They need to emphasize the WHY of it, not just the WHAT. I can usually look at the diff and ascertain the what in about 3.8 seconds (eg this is a change to the update method on the X controller), but the why? That escapes me. I don’t have the context you had when you wrote it. Commit messages help debuggers get context. If your commit messages are as descriptive as “more testing”, “fixed it”, “robocop”, etc, then you’re not helping the people who follow you (read: me) from getting information they need to understand how the code is the way it currently is. git rebase —interactive is your friend, andgit absorb (third party) is even betterer. You should use these commands to clean up your commits (message and structure) before you flip your PR from draft for review.

Reviewers: REMEMBER: you’re approving this code to go into the codebase permanently. If a PR doesn’t align to best practices on commit messages and/or structure, then IT IS YOUR RESPONSIBILITY to block that PR and request changes until it is in good shape.

Everyone: I’ve been doing this for, like, forever. Like... literally, even before git. 😛 I would really love recommendations for good resources to read/watch/review for writing good commit messages, good PR descriptions, (re)structuring clean commit streams, contributing to open source, etc. I simply don’t have any links to contribute yet.

So… if you have written (or are reviewing!) a PR that has more than 10ish commits, or if your commit messages do not have both a noun and a verb in them, let alone a complete descriptive sentence… then we need to talk! I will happily pair with anyone who wants to learn how to write good commit messages and/or rewrite git history into a clean and clear PR.

❤️❤️❤️