Large PR Splitting Workflow
Decompose an oversized change into reviewable slices: by layer, by feature flag, or by dependency order, each slice independently green.
Objective
Turn an unreviewable mega-PR into a sequence of slices a reviewer can hold in mind, each shippable and revertible on its own.
Environment
- An oversized PR or branch accumulating work
- A feature flag system or config gates
- A stacked-PR or sequential-merge capability
Steps
1. Map the change into natural seams
Identify the boundaries the work already has: new module versus integration, data layer versus UI, independent sub-features, or preparatory refactors.
Expected state: A slice plan exists where each slice has a one-line purpose.
2. Order by dependency, lead with prep
Sequence slices so refactors and new abstractions land first, keeping every intermediate state compiling and green.
Expected state: Each slice merges with the full suite passing at that commit.
3. Gate behavior with flags, not absence
Slice by feature flag so code paths merge inert rather than half-written, keeping production behavior off until the final slice.
Expected state: Intermediate slices ship with zero user-visible change.
4. Review slices as a series with context
Give reviewers the series map up front, so each slice review carries the plan and the prior slices as context rather than appearing arbitrary.
Expected state: Reviewers reference the plan; no slice is reviewed as an unexplained fragment.
5. Close the series deliberately
The final slice flips the flag or removes the scaffolding, and the series closes with a summary linking all slices for future archaeology.
Expected state: The feature is on, scaffolding is removed, and the series index exists.
Expected outcome
Oversized changes landing as ordered, individually-green slices with flag-gated behavior, each reviewable in one sitting and revertible alone.
Verification
Every intermediate commit is green in CI; each slice received a substantive review; a revert of one slice does not strand the others.
Every big change has seams; find them before reviewers suffer
The mega-PR is not one change; it is several changes stapled together. Splitting along the natural seams — prep refactor, inert module, flag-gated wiring, final activation — turns an hour of skim-review into four focused ones.
mega-PR: gift-card payments (2,340 lines) -> series:
#1 prep: extract PaymentProvider interface
(refactor, no behavior change, 118 lines)
#2 core: gift-card provider module (inert,
not registered, 612 lines)
#3 data: card-balance table + migrations
(additive, 214 lines)
#4 wiring: register provider behind flag
gift_cards=off (96 lines)
#5 activate: flag default on + remove
scaffolding (44 lines)
review experience: 5 focused reviews,
each green at merge, revertable alone
(vs 1 skim of 2,340 lines)Preparation slices earn their own review
The refactor that extracts an interface looks trivial bundled into the feature PR, where it hides risk inside volume. As its own slice it gets real scrutiny for exactly the compatibility questions that matter, and the feature slices above it become smaller and more honest.
Flags let code merge before it is wanted
Waiting until a feature is complete forces the mega-PR. Merging each module inert — unregistered, flag-off — means the code integrates continuously while behavior stays off, and the final activation slice is forty lines that a product manager can read.