GitHubProduct Thinking7 min readMaking code review a shared artifact
A diff, a comment thread, and a merge button that waits.
- The surface
- Opening a pull request, reviewing the diff, leaving line comments, and the gate in front of the merge button.
- What the user wants
- I want my change looked at by someone who knows this code, and I want to know exactly what is blocking it from shipping.
The prefilled pull request form
After a push, the repository page surfaces a banner offering to open a pull request from that branch, and the form prefills title and description from the commits. Repositories can supply a template.
Reducing the cost of starting
The gap between finishing work and asking for review is where changes go stale. Prefilling means the author edits rather than composes. A repository template moves review standards from a wiki nobody opened into the field the author is already typing in.
The unified change view
A pull request is a set of tabs over one object: conversation, commits, checks and files changed. The diff shows only the lines touched, with surrounding context expandable.
One artifact, many lenses
Review needs different questions answered at different moments: what changed, why, and does it pass. Keeping them as tabs on one object means a reviewer never loses their place or has to reconcile two systems. Hiding untouched lines is a direct attack on reviewer cognitive load: How much a person has to hold in mind at once to get through a task..
Line-anchored comments
A comment attaches to a specific line and stays attached as the conversation continues, and threads can be marked resolved.
Put the discussion where the evidence is
Feedback written in a separate channel forces every reader to rebuild the mapping between words and code. anchoring: The first number you see shapes every judgement that follows. removes that translation step for everyone who arrives later. Resolution turns a wall of comments into a checklist with a visible end.
Batched review submission
Starting a review holds comments as pending until the reviewer submits them together, with a required state of comment, approve, or request changes.
Batching to protect the recipient
Ten notifications as a reviewer thinks out loud makes the author react to half-formed opinions. Batching gives the reviewer room to change their mind before anyone sees it. Forcing an explicit verdict at submission removes the ambiguity of a review that is technically finished but says nothing.
Suggested changes
A reviewer can write a suggestion block inside a comment, and the author can commit it from the review interface without leaving the browser.
Collapse the loop between feedback and fix
Most review comments are small: a name, a missing guard, a typo. Turning the suggestion into a committable action removes a context switch back to the editor for both people. It also makes the reviewer phrase the fix precisely instead of gesturing at it.
Checks and the merge gate
Status checks report into the pull request, and branch protection can hold the merge button until required checks pass and required reviewers approve.
Make the policy visible where the decision happens
A rule written in a handbook is enforced by memory and social pressure. A disabled merge button with a named unmet condition converts policy into an interface state nobody argues with. The list of unmet conditions also tells the author exactly what to do next.
Where a change waits
What not to copy
- Large pull requests defeat the whole design. The diff view scales visually but human attention does not, and the product does nothing to stop a fifty file change from being rubber stamped.
- Approval carries social weight the interface ignores. Request changes reads as confrontational in many teams, so reviewers approve with a comment and the gate quietly stops working.
- Review order follows file paths, not importance. Reviewers read alphabetically and spend their freshest attention on a lockfile.
- Branch protection and required checks live in repository settings that most contributors cannot see. When the merge button is blocked, the person affected often has no route to understand or change the rule.
The takeaway
When you enforce a policy, render its unmet conditions in the place where the blocked person is standing.
Finished the teardown? Bank it and the day counts toward your run.
Where the principles come from
- The Design of Everyday Things (constraints and feedback), Don Norman
- Don't Make Me Think, Steve Krug
- Visibility of System Status (heuristic 1), NN/g
- Accelerate, Nicole Forsgren, Jez Humble, Gene Kim
Written from public behaviour of the product, not from inside it. Interfaces change often, so treat the flow described here as of the time of writing and check the live product before quoting it.