The diff and the review — what reviewers look at and why small PRs matter

The diff is the artefact the reviewer reads. Four questions: Is this correct? What are the side-effects? Can it be reversed? Does the intent match the change? Each has a cognitive cost that grows non-linearly with PR size. A 50-line diff is reviewed carefully. A 5,000-line diff is rubber-stamped.

Two-dot and three-dot

The two-dot diff shows what is on the head branch but not on the base; the three-dot diff shows what is on the head since the merge base. For an infrastructure team, the distinction matters: a PR with a stale base ref will look much bigger in the two-dot view because main has been advancing while the branch was open.

git diff main..feature/login-v2
git diff main...feature/login-v2

If main advanced by ten commits after the branch forked, the two-dot diff includes those ten commits plus the branch’s own — a misleading view that mixes “what I changed” with “what other people changed”. The three-dot range isolates the branch’s own contribution since the merge base, which is the reviewer’s actual scope.

flowchart LR
    H["feature/login-v2"] --> C1["commit a"]
    C1 --> C2["commit b"]
    C2 --> C3["commit c"]
    M["merge base"] --> C1
    B["main tip"] --> X1["main commit 1"]
    X1 --> X2["main commit 2"]
    X2 --> B
    M --> X1
    A["main..feature (2-dot)"] -. "includes a,b,c and 1,2" .-> H
    B["main...feature (3-dot)"] -. "includes only a,b,c" .-> H

git request-pull origin/main git@github.com:team/repo.git feature/login-v2

git request-pull produces a paste-able summary — commits, diffstat, fetch URL. The web UI of every modern forge defaults to the three-dot view for the same reason.

What reviewers actually look at

A reviewer of an infrastructure change is checking four things:

1. Correctness. Does the change do what the description says?
2. Side-effects. What else does this touch? A Terraform IAM attachment asks: what does this policy grant, to whom, and is the principal scoped tightly enough? Side-effects are where most production incidents enter through an infrastructure PR.
3. Reversibility. A new resource is trivially reversible; a state-altering change or credential rotation is much harder.
4. Intent. Does the description match the change? “bump timeout” that rewrites a routing table is a smell.

Production discipline

1. Three-dot diff is the review surface. Flag PRs that include main-line changes.
2. PR size budget. Small if it changes fewer than ~400 lines including tests; otherwise split.
3. One thing per PR. Refactor, feature, and fix are three PRs.
4. Review side-effects, not just the diff. A reviewer who has not run the plan has not reviewed a Terraform change.

Cross-course references

• CI/CD Pipeline Patterns - Part III (FastCI): PR size and CI runtime.
• Terraform for Production Sysadmins - Part XI (PRWorkflows): the small-PR discipline for Terraform.
• Ansible for Production Sysadmins - Part XXXVIII (ReviewPatterns): review patterns for playbooks.

Quiz