1. LandOffer
  2. Blog
  3. All articles
  4. Make a Pull Request Small Enough to Review Without Hiding Its Context

Engineering Practice

Make a Pull Request Small Enough to Review Without Hiding Its Context

Split a broad pull request into coherent, runnable review units while preserving callers, tests and dependencies. Use a complete original sequence, two filled descriptions and actually checked local snapshots to define each review claim.

9 min readLandOffer team

Make a pull request small by giving it one coherent purpose while retaining the files, callers and tests needed to judge it. Separate unrelated cleanup from behavior changes, preserve a working intermediate state, and explain dependencies in the description. A reviewer should be able to understand what this change does now, why it exists and what evidence applies to this version without reconstructing the author's entire project.

This LandOffer.ai guide turns an original fictional training-schedule change into a complete review sequence and two filled review descriptions. We executed isolated Python snapshots to compare their behavior and saved their differences. No remote repository, pull request, CI service, reviewer approval, merge or production deployment was created or operated.

Two artisans examine stained-glass panel sections beside a complete window pattern on a workbench.

Choose the question a reviewer can actually answer

A small PR should support a clear judgment: does this extraction preserve behavior, does this fix handle the missing value, or does this integration use the new contract correctly? A broad rename and formatting pass can obscure which differences answer those review questions.

Google's small-change guidance describes a self-contained change with related tests and enough context, including working intermediate states. It treats conceptual focus as more important than a rigid line count. These are published engineering practices, not a universal rule that a particular number of lines guarantees an easy or safe review.

Before splitting, list the behaviors and responsibilities in the original branch. Mark which edits alter behavior, which preserve it, which are required to support that behavior and which are optional. If a new helper has no caller until a later PR, consider keeping its first use with it so reviewers can inspect the actual abstraction rather than a speculative interface.

Do not cut a change at arbitrary file boundaries. Moving an implementation without its import update can leave the intermediate tree broken. Separating a fix from the only test that exposes it can conceal the reason for the change. A smaller diff that requires an unreviewed future patch to work is not a useful intermediate deliverable.

Worked asset: turn the broad branch into a reviewable sequence

The fictional Finch training portal shows session length in a schedule list and a detail panel. Its source supplies either a nonnegative whole number of minutes or None when length is unknown. Zero means a known zero-minute length; it must not be treated as missing.

Author Melina's initial branch mixes four changes: consolidate duplicated formatting, display unknown length as “Not available,” rename the schedule modules and reformat unrelated navigation code. Reviewer Dov needs the duration change's context, not a broad tour of navigation styling. Product owner Anouk confirms the unknown-versus-zero distinction within this invented case.

The original local snapshot renders known values as, for example, “Duration: 45 min” in the list and “Session length: 45 min” in the panel. For None, it renders the misleading strings “Duration: None min” and “Session length: None min.” These are actual outputs of our tiny synthetic Python example, not a discovered defect in a real portal.

Melina completes this sequence plan before asking for review:

Review unit Included change and context Intermediate behavior Dependency and disposition
PR-A: Extract shared session-length formatting without changing labels Add one formatting helper, route both existing callers through it and retain known/unknown characterization checks Known inputs remain unchanged; the existing None min defect deliberately remains visible Based on snapshot S0. Useful consolidation with real callers, not an unused helper. Review as behavior-preserving
PR-B: Distinguish unknown session length from zero minutes Change the helper's None handling, add unknown/zero checks at both callers and update the local behavior note Both callers show Not available for None; zero remains 0 min Based on PR-A's exact snapshot S1. Review the missing-value behavior, not the extraction again
Separate optional proposal Module rename and navigation reformatting No required contribution to the duration fix Excluded from both PRs. No third PR or cleanup approval is invented

PR-A is not described as fixing the user problem. It creates a smaller seam for the fix while preserving the current behavior. PR-B changes that seam and the expectations that explain it. If extraction is unnecessary in the actual codebase, the team can choose one coherent fix instead; creating two PRs is not a goal by itself.

Both snapshots are runnable. PR-B's tests belong with its changed behavior rather than being deferred to an imagined follow-up. The optional rename remains outside the sequence, so finishing PR-B does not depend on approving an unrelated cleanup.

Show the dependency without making it the reviewer's puzzle

State the base and what the reviewer is comparing. In this example, PR-A compares S0 with S1; PR-B compares S1 with S2. Looking at S2 against S0 would combine the extraction and fix again. That comparison helps verify the final result across the sequence. For PR-B's focused review, also provide S1-to-S2 so the reviewer can isolate the actual behavior change.

The local files here are snapshots, not real branches or numbered remote PRs. In an actual workflow, link the dependent change, explain which base contains the prerequisite and follow the repository's supported review process. Do not assume every hosting product automatically maintains a stack or updates its base when an earlier change lands.

If PR-A changes during review, Melina must update PR-B against the new prerequisite and rerun the relevant checks. An earlier pass on S1 does not cover a different helper signature or caller contract. Record which comparison is current; an old screenshot of a green build can outlive the code it described.

Reviewability and merge readiness are related but different. A reviewer can discuss PR-B while PR-A is unsettled, but the author must not land a dependent change into a base that lacks its prerequisite. The specific branch, CI and integration mechanics belong to the actual repository; this article does not choose its merge or rebase policy.

Worked asset: complete descriptions and verification scope

Google's description guidance asks authors to explain what changes and why, including context not apparent in code. It also recommends checking the description again when review changes the implementation. A title such as “Phase 1” leaves future readers with almost none of that information.

Melina prepares this full illustrative description for the first unit:

Extract session-length formatting for both schedule views.

The list and detail panel currently repeat the same minute-label expression. Move that expression into a shared helper and use it from both callers. This makes the subsequent missing-length change reviewable in one place.

This unit preserves existing output, including the known None min defect. It does not claim to fix unknown length. Known zero, one and forty-five minutes retain their current labels in both views. The snapshot comparison includes both callers, the helper and characterization expectations.

Local evidence: compare S0 with S1, then inspect the eight recorded caller/input outputs for each. All corresponding outputs match. These are isolated Python functions; no rendered browser or real schedule API was tested.

Next dependency: the proposed PR-B changes missing-length behavior on top of this snapshot. It is not required for S1 to import and run. Module renaming and unrelated navigation formatting are excluded.

Her second description records a different decision:

Show unavailable session length without converting zero to missing.

Based on S1 from PR-A, return Not available only when length is None. Both schedule callers use the shared result. Keep 0 min, 1 min and 45 min unchanged. Update the behavior note and checks with this fix.

Anouk's requirement distinguishes unknown from a known zero. Avoid a truthiness fallback such as treating every false-like value as absent. The fixture domain is nonnegative integer minutes or None; it does not define formatting for floats, negative values, strings or booleans.

Local evidence: S2's eight caller/input checks pass against explicit expectations. The two unknown outputs differ from S1 as intended; the six known-value outputs are unchanged. These results apply to the saved S2 snapshot. The actual portal's serialization, browser presentation and accessibility remain untested.

Review request: inspect the helper's exact missing-value condition, both caller outputs and the documented domain. Do not treat the isolated checks as full application verification. The optional module rename and navigation formatting remain excluded.

Those descriptions include the relevant limitations without burying the change under process history. They tell Dov where to start, what must stay stable and which unfinished checks cannot be claimed from the local evidence.

One artisan holds a stained-glass section while another points to its edge beside neighboring panels and a full pattern.

Match tests to the claim made by each unit

We actually ran the three original snapshots against four inputs at two callers: zero, one, forty-five and None. Each snapshot includes its own eight unittest cases, run in a separate Python process; all 24 passed. The local fixture also records explicit outputs and the two sequential source/test diffs. That produces eight recorded outputs per snapshot. S0 and S1 agree on all eight, preserving even the defect. S2 changes the two None outputs and preserves the six numeric outputs. The saved diffs identify the extraction separately from the fix.

This is bounded evidence. Characterization preserves observed behavior for selected inputs; it does not declare that behavior correct. The explicit S2 expectations define the intended correction in this teaching example. Neither set establishes that a real service always sends the declared input type or that a browser renders the resulting copy appropriately.

Google's reviewer guidance calls for appropriate tests and broader code context, including whether assertions are meaningful. A passing test that repeats the implementation's expression can miss the same mistake. Here the expected strings are written explicitly, and zero is included because it distinguishes None handling from an overly broad false-like fallback.

For an actual integration, inspect the producer's nullable contract and relevant callers. If a different field can also be missing, identify that separate requirement instead of quietly changing its behavior. If a caller wraps the label for localization or assistive technology, the local formatting result does not replace those checks. Melina owns checking the real nullable producer contract and Dov owns reviewing the resulting integration evidence. Browser and accessibility review still need an agreed environment and qualified owner before anyone presents the actual portal change as ready to land.

Keep the context current as review changes the scope

Suppose Dov asks whether the extraction should live in the existing display module instead of a new utility module. That is a design question that can change PR-A and its dependent comparison. Melina should revise the actual snapshots and evidence, then update both descriptions. Merely replying that the code moved leaves the old review instructions misleading.

If the team removes the extraction entirely, rewrite the remaining PR around the final fix. Do not retain an obsolete “second phase” title or refer to a prerequisite that no longer exists. Preserve relevant decisions in the record, but make the current trigger and outcome understandable to a reviewer who has not followed the discussion.

A coherent PR can still be large when its behavior and compatibility boundaries genuinely need to be judged together. Explain why its parts must be judged together, identify the difficult boundaries and agree a review approach with qualified reviewers. Do not omit tests, generated interfaces or affected documentation simply to make a line counter smaller. Conversely, a small patch can alter a widely used contract and deserve substantial review.

For the next request, assemble the focused diff, its exact base, the behavior claim and the evidence for that version. More engineering guides are available from LandOffer.ai. Ask for a concrete review judgment against the named base and current evidence. Keep dependent changes runnable and update their descriptions when a prerequisite changes. A smaller unit helps when its boundaries make the reasoning clearer.

Sources and Further Reading