Trunk-Based Development: Why Short-Lived Branches Win

# ❌ Long-lived feature branches — the traditional model
main ─────────────────────────────────────────────
       \                                    /
        feature/auth-redesign ─────────────  (2 weeks)
                 \                  /
                  sub-branch ─────  (1 week)
 
# 3 weeks of divergence, massive merge, manual conflict resolution

# ✅ Trunk-based: short-lived branches merged within 1-2 days
main ──●──●──●──●──●──●──●──●──●──●──●──●──
       │     │        │  │     │        │
       └─●─┘ └──●──┘  └┘ └─●─┘ └──●──┘
 
# Each branch lives hours to 2 days max
# Small diffs, easy review, minimal conflicts

// Feature flag implementation — can be as simple as environment config
interface FeatureFlags {
  newCheckoutFlow: boolean;
  betaDashboard: boolean;
  experimentalSearch: boolean;
}
 
function getFeatureFlags(): FeatureFlags {
  return {
    newCheckoutFlow: process.env.FF_NEW_CHECKOUT === 'true',
    betaDashboard: process.env.FF_BETA_DASHBOARD === 'true',
    experimentalSearch: process.env.FF_EXPERIMENTAL_SEARCH === 'true',
  };
}

// ❌ Keeping half-finished UI in a branch for weeks
// Meanwhile, 5 other developers change the same components
 
// ✅ Merging incomplete work behind a flag — code is on main, hidden from users
function CheckoutPage() {
  const flags = useFeatureFlags();
 
  if (flags.newCheckoutFlow) {
    return <NewCheckout />;  // Work in progress, only visible internally
  }
 
  return <CurrentCheckout />;  // Production users see this
}

# .github/workflows/ci.yml — required checks for trunk
name: CI
on:
  pull_request:
    branches: [main]
 
jobs:
  quality-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
 
      - name: Install dependencies
        run: npm ci
 
      - name: Type check
        run: npx tsc --noEmit
 
      - name: Lint
        run: npx eslint . --max-warnings 0
 
      - name: Unit tests
        run: npx jest --ci --coverage
 
      - name: Integration tests
        run: npx jest --ci --selectProjects integration
 
      - name: Build
        run: npm run build

# Branch protection rules (configured in GitHub settings)
# Required for main branch:
#   ✓ Require pull request reviews (1 reviewer)
#   ✓ Require status checks to pass (quality-gate)
#   ✓ Require branches to be up to date before merging
#   ✓ Restrict who can push directly to main

# ❌ One PR that does everything (800 lines changed)
feat: implement user settings page
- Add settings API endpoints
- Create settings form components
- Add form validation
- Update navigation
- Add settings E2E tests
- Update user model with preferences
 
# ✅ Multiple small PRs (each under 200 lines)
# PR 1: Add preferences field to user model + migration
# PR 2: Add GET/PUT /api/settings endpoints
# PR 3: Create SettingsForm component (behind feature flag)
# PR 4: Wire form to API, add validation
# PR 5: Add navigation link (flag-gated)
# PR 6: Enable feature flag, remove old code

# Stacked PRs workflow — each builds on the previous
git checkout main && git pull
git checkout -b settings/model     # PR 1: schema change
# ... commit, push, open PR
 
git checkout -b settings/api       # PR 2: built on model changes
# ... commit, push, open PR (base: settings/model)
 
git checkout -b settings/ui        # PR 3: built on API changes
# ... commit, push, open PR (base: settings/api)

# Pull main into your branch at least once a day
git checkout my-branch
git fetch origin
git rebase origin/main
 
# If conflicts occur, they're small — just today's divergence
# Fix conflicts, then continue
git add .
git rebase --continue

# ❌ Two-week branch: 15 files conflicted, 3 hours to resolve
# ✅ One-day branch: 1 file conflicted, 5 minutes to resolve

// Metrics that indicate healthy trunk-based development
interface TrunkMetrics {
  // How long a branch exists before merging
  branchLifespanHours: number;   // Target: < 48 hours
  
  // Lines changed per PR
  prSize: number;                // Target: < 200 lines
  
  // Time from PR open to merge
  reviewCycleHours: number;      // Target: < 8 hours
  
  // How often main is deployed
  deployFrequency: string;       // Target: daily or more
  
  // Percentage of main commits that pass CI
  greenBuildRate: number;        // Target: > 98%
  
  // Time to fix a broken main
  mainRecoveryMinutes: number;   // Target: < 30 minutes
}

# Quick check: branches older than 2 days
git for-each-ref --sort=-committerdate refs/remotes/origin \
  --format='%(committerdate:relative) %(refname:short)' \
  | head -20
 
# If you see branches older than 2 days, investigate why
# Common causes: blocked on review, scope too large, unclear requirements