Branching and pull request workflow
Branching strategy decides one thing: how often changes integrate. Everything else — review model, release cadence, merge pain — is downstream.
Recommended default
Section titled “Recommended default”Work trunk-based. One shared branch, main. Every developer integrates
at least once a day; most integrate several times. Incomplete work hides
behind feature flags, not branches. Branches, when used at all, live a day
or two — never longer.
- Integrate daily, at least. A change more than a day stale is a merge conflict rehearsing itself.
- Feature flags, not feature branches. Merge incomplete code dark; flip when it’s ready. Set a delete date on the flag the day you add it — otherwise they accumulate.
- Branch-by-abstraction for larger changes. Introduce the abstraction
first, migrate callers, then swap the implementation. Land it all on
main. - Review at the speed of typing. Pair programming counts. Async review is fine when the round-trip is under an hour — beyond that, cycle time suffers by design.
- CI on every commit to
main. A red trunk stops the line. Fix it now, not tomorrow. - Release branches only at ship time. Cut just before release. Fix
on
main, cherry-pick to the release branch. Never the reverse.
Why this is the default
Section titled “Why this is the default”Integration frequency has a remarkably powerful effect on how a team operates. Small, frequent merges resolve conflicts with full context. Weekly merges resolve them with none — and produce the variance problem: most weeks are fine, occasional weeks go very badly.
The second-order cost is worse. Long branches quietly deter refactoring — everyone knows a bigger change makes integration harder, so nobody proposes one. Feature Branching, in Dan Bodart’s phrase, is a poor man’s modular architecture: teams reach for branches when the code won’t let them integrate incomplete work safely. Fix the code, not the workflow.
The corporate form
Section titled “The corporate form”Some organisations can’t run straight-to-trunk. Regulated environments require signed per-change approvals. Distributed teams across time zones can’t sustain fast review. Contractor-heavy teams need PRs as a trust boundary.
Then run scaled trunk-based: short-lived branches (a day or two, never
more), one reviewer, squash-merge to main, and a review SLA in the low
tens of minutes. Keep everything else — flags, small diffs, protected
main, red-build stops the line. Pre-integration review always introduces
latency, and latency lowers integration frequency by design; the SLA is
how you cap the damage.
The honest framing: if you can name the regulator, the trust boundary, or the time-zone spread forcing PR review, you’re in scaled trunk-based. If you can’t, you’re paying its cost without its benefit — and the answer is to change the context, not settle.
Hitting the review SLA
Section titled “Hitting the review SLA”Fast review does not happen by asking for it. The levers:
- Named reviewer, not “the team”. Broadcast requests get ignored. Assign one person; escalate if they’re not around.
- Reviewer-of-the-day rota. One engineer’s primary job today is unblocking PRs. Rotate daily so it doesn’t burn a career.
- Ship / Show / Ask. Most changes are Ship (merge, no review) or Show (merged, FYI post-hoc). Reserve blocking review for the genuinely uncertain — that’s what the SLA is for. See code review expectations for the triage in full.
- Cap the diff. Under ~200 lines. A PR that fits in a coffee break gets reviewed in one; one that needs a focused hour waits until tomorrow.
- Self-review before requesting. Read your own diff, run the checks locally. The reviewer’s first pass is not for finding your typos.
- PR-open-time on a dashboard. What gets measured gets defended. Median time-to-first-review is the number to watch.
Common mistakes
Section titled “Common mistakes”- Calling GitHub Flow “trunk-based”. Feature branches per ticket with mandatory PR review is scaled trunk-based at best — and only if branches live a day or two and review lands in minutes.
- Long-lived
developbranch. A second trunk you have to keep in sync with the first. Drop it. - Environment branches (
main→staging→prodwith cherry-picks between). An anti-pattern. Environments are config, not source. - Fixing on the release branch first. The bug regresses the moment
the next release cuts. Fix on
main, cherry-pick out. - Feature flags with no expiry. Set a delete date; enforce it in review.
- Rebase-vs-merge debates in review. Pick one, write it here, stop arguing.
Step by step
Section titled “Step by step”- Pull latest
main. - Write a small increment — an hour or two of work, not a day.
- If working solo and CI is fast, push straight to
main. If pairing, the pair is the review. If your organisation requires PRs, open one immediately and expect it merged within the hour. - Watch CI. A red trunk stops the line.
- Repeat several times a day.
mainis always releasable; the flag decides what’s on.
Further reading
Section titled “Further reading”- Trunk-Based Development — the
canonical reference. See especially
/styles/,/short-lived-feature-branches/,/branch-for-release/, and/youre-doing-it-wrong/. - Martin Fowler, Patterns for Managing Source Code Branches — the patterns behind the tradeoffs (Mainline, Feature Branching, Continuous Integration, Release Branch, Pre-Integration Review).
- Rouan Wilsenach, Ship / Show / Ask — the review triage that makes minute-scale SLAs realistic.
- Paul Hammant, Introducing Branch by Abstraction — the technique for landing large changes on trunk without a long-lived branch.