Trunk-Based Development | Faster Integration Guide
Implement trunk-based development with short-lived branches and continuous integration. GitScrum supports rapid feedback workflows for faster delivery.
9 min read
Integrate continuously. GitScrum supports trunk-based development workflows where teams integrate frequently to the main branch for faster feedback and delivery.
Understanding Trunk-Based Development
Core Concepts
TRUNK-BASED DEVELOPMENT:
┌─────────────────────────────────────────────────────────────┐
│ │
│ THE CONCEPT: │
│ ──────────── │
│ Everyone integrates to main/trunk frequently │
│ Short-lived branches (hours, not weeks) │
│ Continuous integration to shared codebase │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ TRUNK-BASED: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ ││
│ │ main ─●──●──●──●──●──●──●──●──●──●──●──●──→ ││
│ │ ╲╱ ╲╱ ╲╱ ╲╱ ╲╱ ││
│ │ ─● ─● ─● ─● ─● ││
│ │ (short branches - hours/day) ││
│ │ ││
│ │ • Small, frequent merges ││
│ │ • Conflicts are small and easy ││
│ │ • Always shippable ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ VS GITFLOW: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ ││
│ │ main ─●────────────────────────●────→ ││
│ │ develop ─●──●──●──●──●──●──●──●──●●───→ ││
│ │ ╲ ╱ ││
│ │ feature ──●────●────●────●────●─ ││
│ │ (weeks/months) ││
│ │ ││
│ │ • Big merges at end ││
│ │ • Integration pain ││
│ │ • "Merge hell" ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ KEY DIFFERENCE: │
│ Trunk-based = Integrate often, small batches │
│ GitFlow = Integrate at end, big batches │
└─────────────────────────────────────────────────────────────┘
How It Works
The Workflow
TRUNK-BASED WORKFLOW:
┌─────────────────────────────────────────────────────────────┐
│ │
│ DAILY FLOW: │
│ ─────────── │
│ │
│ 1. PULL LATEST │
│ git checkout main │
│ git pull │
│ │
│ 2. CREATE SHORT BRANCH │
│ git checkout -b add-login-button │
│ (Branch lives hours, not weeks) │
│ │
│ 3. MAKE SMALL CHANGE │
│ - Implement small, complete piece │
│ - Add tests │
│ - Keep it focused │
│ │
│ 4. PUSH AND PR │
│ git push origin add-login-button │
│ - Create PR │
│ - Get quick review │
│ │
│ 5. MERGE SAME DAY │
│ - Merge to main │
│ - Delete branch │
│ - Start next piece │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ BRANCH LIFESPAN: │
│ ──────────────── │
│ ✅ Hours ← Ideal │
│ ✅ 1 day ← Good │
│ ⚠️ 2-3 days ← Getting long │
│ ❌ 1 week+ ← Not trunk-based │
│ │
│ RULE: "If branch lives past end of day, something's wrong"│
└─────────────────────────────────────────────────────────────┘
Breaking Down Work
SMALL, COMPLETE CHANGES:
┌─────────────────────────────────────────────────────────────┐
│ │
│ BAD: BIG FEATURE BRANCH │
│ ───────────────────── │
│ │
│ "Implement user authentication" │
│ • Login form │
│ • Password reset │
│ • OAuth integration │
│ • Session management │
│ • 2FA │
│ │
│ → 3 weeks of work → Big merge → Conflicts │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ GOOD: SERIES OF SMALL CHANGES │
│ ───────────────────────────── │
│ │
│ Day 1: │
│ ├── "Add User model" (1 hour) │
│ ├── "Add login form UI" (2 hours) │
│ └── "Add login API endpoint" (3 hours) │
│ │
│ Day 2: │
│ ├── "Connect login form to API" (2 hours) │
│ ├── "Add session token storage" (2 hours) │
│ └── "Add logout functionality" (2 hours) │
│ │
│ Each merge: Small, easy to review, easy to rollback │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ SLICING TECHNIQUES: │
│ ─────────────────── │
│ │
│ HORIZONTAL: │
│ Backend first, then frontend │
│ DB first, then API, then UI │
│ │
│ VERTICAL (Better): │
│ Thin slice through all layers │
│ "User can log in" end-to-end │
│ │
│ INCREMENTAL: │
│ Basic version first, enhance later │
│ "Login works" → "Add remember me" → "Add 2FA" │
└─────────────────────────────────────────────────────────────┘
Feature Flags
Hiding Incomplete Work
FEATURE FLAGS FOR TRUNK-BASED:
┌─────────────────────────────────────────────────────────────┐
│ │
│ THE PROBLEM: │
│ ──────────── │
│ Feature takes 2 weeks to complete │
│ But we're merging to main daily │
│ How to hide incomplete features? │
│ │
│ THE SOLUTION: FEATURE FLAGS │
│ ─────────────────────────── │
│ │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ // Code is on main, but hidden behind flag ││
│ │ ││
│ │ if (featureFlags.isEnabled('new-checkout')) { ││
│ │ return <NewCheckoutFlow />; ││
│ │ } else { ││
│ │ return <OldCheckoutFlow />; ││
│ │ } ││
│ │ ││
│ │ // Incomplete code is safe in production ││
│ │ // Enable flag when feature is complete ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ ROLLOUT PROCESS: │
│ │
│ Week 1: Merge UI changes (flag OFF for everyone) │
│ Week 2: Merge backend changes (flag OFF) │
│ Week 3: Feature complete │
│ → Enable for internal users │
│ → Test in production │
│ Week 4: Enable for 10% of users │
│ Week 5: Roll out to 100% │
│ Week 6: Remove flag and old code │
│ │
│ SEPARATION: │
│ ──────────── │
│ DEPLOY: When code goes to production (daily) │
│ RELEASE: When users see feature (when ready) │
└─────────────────────────────────────────────────────────────┘
CI/CD Requirements
Keeping Main Healthy
TRUNK-BASED CI/CD:
┌─────────────────────────────────────────────────────────────┐
│ │
│ REQUIREMENTS: │
│ ───────────── │
│ Trunk-based needs strong CI/CD │
│ Main must always be deployable │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ PRE-MERGE CHECKS: │
│ ───────────────── │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ PULL REQUEST: add-login-button ││
│ │ ││
│ │ AUTOMATED CHECKS: ││
│ │ ✅ Lint passing ││
│ │ ✅ Unit tests passing (423 tests) ││
│ │ ✅ Integration tests passing (87 tests) ││
│ │ ✅ Build successful ││
│ │ ✅ Security scan clean ││
│ │ ✅ Code coverage >80% ││
│ │ ││
│ │ HUMAN CHECKS: ││
│ │ ✅ Code review approved (2) ││
│ │ ││
│ │ [Merge when ready] ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ POST-MERGE: │
│ ─────────── │
│ • Full test suite runs │
│ • Deploy to staging automatically │
│ • Smoke tests │
│ • Deploy to production (or queue) │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ IF BUILD BREAKS: │
│ ──────────────── │
│ │
│ 🚨 STOP THE LINE 🚨 │
│ │
│ 1. All hands: Fix the build │
│ 2. No new merges until fixed │
│ 3. Revert if can't fix quickly │
│ │
│ Rule: "If you break the build, fixing it is your #1 job" │
└─────────────────────────────────────────────────────────────┘
Code Review
Fast Reviews
TRUNK-BASED REVIEWS:
┌─────────────────────────────────────────────────────────────┐
│ │
│ SMALL PRS = FAST REVIEWS: │
│ ───────────────────────── │
│ │
│ TRADITIONAL: │
│ PR: 50 files, 2000 lines │
│ Review: "I'll look at it later..." (3 days later) │
│ │
│ TRUNK-BASED: │
│ PR: 3 files, 50 lines │
│ Review: "Done in 15 minutes" │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ REVIEW EXPECTATIONS: │
│ ──────────────────── │
│ │
│ TEAM AGREEMENT: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ • PRs reviewed within 2 hours ││
│ │ • Small PRs prioritized ││
│ │ • Async review is default ││
│ │ • Pair programming = pre-reviewed ││
│ │ • Blocking comments rare ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ PAIR PROGRAMMING ALTERNATIVE: │
│ ───────────────────────────── │
│ If you paired on the code: │
│ • Already reviewed during pairing │
│ • Fast merge, maybe just 1 reviewer │
│ • Shared ownership │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ REVIEW SIZE GUIDE: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ LINES TIME TO REVIEW DEFECT FIND RATE ││
│ │ ───── ────────────── ──────────────── ││
│ │ 50 15 min High ││
│ │ 100 30 min Good ││
│ │ 200 1 hour Medium ││
│ │ 500+ 2+ hours Low (reviewer fatigued) ││
│ │ ││
│ │ TARGET: <200 lines per PR ││
│ └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
Adoption Tips
Getting Started
ADOPTING TRUNK-BASED:
┌─────────────────────────────────────────────────────────────┐
│ │
│ PREREQUISITES: │
│ ────────────── │
│ ☐ Fast CI pipeline (<10 min) │
│ ☐ Automated testing (good coverage) │
│ ☐ Feature flag infrastructure │
│ ☐ Team commitment │
│ │
│ TRANSITION PATH: │
│ ──────────────── │
│ │
│ STEP 1: SHORTER BRANCHES │
│ From: week-long branches │
│ To: 2-3 day branches │
│ │
│ STEP 2: MORE FREQUENT MERGES │
│ From: Merge at feature complete │
│ To: Merge daily │
│ │
│ STEP 3: FEATURE FLAGS │
│ Add flags for incomplete features │
│ Practice hiding work behind flags │
│ │
│ STEP 4: FULL TRUNK-BASED │
│ Branch lives hours, not days │
│ Multiple merges per developer per day │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ COMMON CHALLENGES: │
│ ────────────────── │
│ │
│ "Our tests are too slow" │
│ → Invest in faster CI (parallel, better tests) │
│ │
│ "Reviews take too long" │
│ → Smaller PRs are faster to review │
│ → Team commitment to fast reviews │
│ │
│ "Features need long branches" │
│ → Learn to slice smaller │
│ → Use feature flags │
│ │
│ "Main might break" │
│ → Better pre-merge checks │
│ → Fast rollback capability │
└─────────────────────────────────────────────────────────────┘