Trunk-Based Development — 40 Feature Branches Caused a 3-Day Merge Hell

Long-lived feature branches are the #1 cause of merge pain in Git. Two developers working on separate branches for 3 weeks will have conflicts when they merge — guaranteed. The codebases diverged too far. Trunk-based development solves this by merging to main multiple times daily. Incomplete features are hidden behind feature flags (if/else blocks that toggle features on/off). The result: no merge hell, continuous integration catches conflicts immediately, and deployment can happen at any time. This guide covers the trunk-based workflow, the incident that triggered a 3-day merge catastrophe, and how to migrate from feature branches to trunk-based development.

Trunk-Based Development Rules and Practices

The core rules are simple but require discipline:

1. Branch from main, merge to main: Every branch starts from main's latest commit. Every branch merges back to main.
2. Short branch lifetime: A branch should exist for hours, not days. 2 days is the maximum. If your feature takes longer, break it into smaller chunks or use feature flags.
3. Feature flags: Hide incomplete features behind toggles. if feature_flag_enabled('new-payment'): new_payment() else: old_payment(). The flag defaults to 'off' until the feature is complete and tested.
4. CI must pass before merge: Every merge to main must pass CI. This prevents broken main from blocking other developers.
5. No direct commits to main: All changes go through short-lived branches reviewed via PR. Main is always in a deployable state.

Benefits: no merge hell, continuous integration catches conflicts immediately, team velocity increases as merge overhead disappears.

# Start from latest main
git checkout main
git pull --rebase origin main
git checkout -b feat/email-validation

# Make small changes (1-2 commits)
echo 'validate() { return true }' > email.js
git add . && git commit -m 'feat: add email validation'

# Merge to main within hours (not days)
git checkout main
git pull --rebase origin main
git merge --squash feat/email-validation
git commit -m 'feat: add email validation'
git push

# For incomplete features: use feature flags
# config.js: export const FEATURES = { newPayment: false }
# app.js: if (FEATURES.newPayment) { showNewPayment() } else { showOldPayment() }

# Delete the branch
git branch -d feat/email-validation