Keep pull requests reviewable
Defect-detection rate falls off a cliff once a diff exceeds roughly 400 changed lines; reviewers skim and approve. The fix is not more diligence, it is a smaller diff.
Procedure
- Measure before splitting:
git diff --stat origin/main...HEAD | tail -1prints total insertions and deletions. Treat 400 changed lines as the soft ceiling, 800 as blocking. - Split along seams that stand alone and can ship independently:
- pure refactor (no behaviour change) first,
- then the new behaviour,
- then tests and docs that depend on both.
- Build the slices with staged hunks:
git add -pfor chunk selection, or stage whole files withgit add -- path. Commit the refactor separately so its diff is mechanical and skimmable. - If the work cannot ship in slices, use a stacked series: branch
feat/part-1, thenfeat/part-2off it, and open PRs in order. Reviewers read top to bottom. - Keep generated files (lockfiles, snapshots, codegen) in their own commit so the hand-written delta is not buried:
git add package-lock.json && git commit -m 'chore: lockfile'. - Track review latency as a signal, not a scold:
gh pr list --json number,additions,createdAtand compare time-to-first-review against diff size. Large diffs sit longer. - When a slice still exceeds the ceiling, note the reason (a single atomic migration, a generated schema) rather than forcing an artificial split.
Pitfalls
- Splitting so finely that each slice is not independently meaningful and the series needs six round-trips to test.
- A refactor slice that quietly changes behaviour, which defeats the whole point of separating it.
- Moving the tests into "part 2", so part 1 lands unverified.
- Forgetting to rebase later slices after part 1 merges, producing a wall of conflicts for the reviewer.
Verification
git diff --stat origin/main...HEAD | tail -1
git log --oneline origin/main..HEAD # one commit per slice, each self-describing
Report the total changed lines per slice and the target ceiling. A PR over 800 hand-written changed lines that cannot ship in pieces should be closed and re-opened as a stack.
Worked example
A 1,400-line PR "add OAuth login" splits into: (1) refactor: extract SessionStore, no behaviour change; (2) feat: google provider, the provider plus its tests; (3) docs: oauth setup. Each part merges on its own; part 2 depends on part 1 only for the interface. Time-to-first-review drops from two days on the monolith to a few hours per slice.