Pull Request Review Workflow
Keep PRs small and single-purpose, distribute review load fairly, enforce response SLAs, and separate blocking findings from suggestions.
Objective
Run reviews that are fast, fair, and decisive: small diffs, SLA-bound first responses, and a clear rule for what blocks merge.
Environment
- A PR platform with review assignment capability
- A team agreement on review SLAs
- A definition of what constitutes a blocking comment
Steps
1. Constrain PR size and purpose
Set a soft limit (say 400 changed lines) and a single-purpose rule, with a documented path for genuinely large changes (stacked PRs or feature slices).
Expected state: Median PR size drops, and large changes arrive as reviewable slices.
2. Assign reviews fairly
Rotate assignment with load balancing rather than volunteering, tracking per-reviewer weekly counts to prevent the same senior doing everything.
Expected state: Review counts per person are visible and roughly even.
3. Enforce first-response SLAs
Agree that reviewers respond within one business day, and surface SLA breaches in team metrics rather than escalating individuals.
Expected state: Median time-to-first-review meets the SLA and trends down.
4. Separate blocking from suggesting
Require reviewers to mark comments as blocking or suggestion, so authors know what must change versus what is food for thought.
Expected state: Merge criteria are the blocking set only; suggestions never gate.
5. Measure the review loop
Track median review latency, re-review rounds, and PRs aging past thresholds, adjusting the process where the metrics hurt.
Expected state: The loop metrics are reviewed monthly with one process change at a time.
Expected outcome
A review process with bounded PR size, fair load, SLA-met responses, and unambiguous merge criteria, measured by loop metrics that keep improving.
Verification
Median PR size, time-to-first-review, and re-review rounds all within targets; no reviewer carries disproportionate load over a month.
Small diffs, fair load, clear blocking
Reviews degrade from three causes: diffs too big to hold in mind, load concentrated on one reviewer, and every comment reading as a veto. Size limits, rotation, and blocking-versus-suggestion markers fix the causes rather than the symptoms.
policy:
soft limit: 400 changed lines (median target: 180)
large change: stacked PRs (base <- feature-slice-1
<- feature-slice-2)
rotation: round-robin, load-balanced
(reviewer A: 11, B: 9, C: 10 this week)
SLA: first response within 1 business day
comment types: [blocking] / suggestion:
"blocking: this swallows the error"
"suggestion: could name this variable `attempts`"
metrics (monthly):
median first response: 4.1h (target: 1 day) OK
median re-review rounds: 1.6
PRs aging > 3 days: 2 (was 14)Blocking versus suggestion is a kindness
When every nitpick carries implicit veto power, authors either over-apply every comment or argue every comment, and both waste the loop. Explicit markers let authors apply suggestions cheaply and contest blocking points specifically, which shortens re-review rounds measurably.
Stacked PRs beat one big one
The 2,000-line feature PR gets skimmed, and skimming is how bugs pass review. Slicing the same work into a base plus dependent stacks gives each reviewer a reviewable unit while still landing the feature coherently — it is a communication choice, not a sacrifice.