Trunk-Based Development with Feature Flags

Overview

Trunk-based development (TBD) is the Git workflow standard for high-performing engineering teams. Instead of maintaining long-lived feature branches, developers commit directly to main (or merge short-lived branches within 1-2 days) and use feature flags to hide incomplete work.

Why This Matters

• -Reduces merge conflicts — daily integration means small diffs
• -Enables continuous delivery — main is always deployable
• -Faster feedback loops — CI runs on every push to main
• -Eliminates integration hell — no more week-long merge sprints

How It Works

Step 1: Create Short-Lived Feature Branches

# Branch from main, name descriptively
git checkout -b feat/user-avatar main

# Work in small increments — aim to merge within 1-2 days
git add -p  # Stage changes interactively
git commit -m "Add avatar upload component skeleton"

Step 2: Use Feature Flags for Incomplete Work

// Instead of hiding work in a branch, hide it behind a flag
if (featureFlags.isEnabled('user-avatar-upload')) {
  return <AvatarUploader />;
}
return <AvatarPlaceholder />;

Step 3: Integrate Daily

# Keep your branch fresh
git fetch origin main
git rebase origin/main

# Push and create PR (should be small, reviewable)
git push -u origin feat/user-avatar

Step 4: Squash Merge to Main

# On GitHub/GitLab, use "Squash and merge" for clean history
# One commit per feature in main branch

Best Practices

• -Commit frequency: At least once per day to main
• -Branch lifetime: Maximum 2 days before merging
• -PR size: Under 400 lines of changes (ideally under 200)
• -CI requirement: All tests must pass before merge
• -Feature flags: Use LaunchDarkly, Unleash, or simple env-based flags

Common Mistakes

• -Keeping feature branches alive for weeks (defeats the purpose)
• -Not rebasing before merge (creates unnecessary merge commits)
• -Skipping CI checks to merge faster
• -Using feature flags without a cleanup process (flag debt)

When NOT to Use Trunk-Based Development

• -Open source projects with external contributors (use fork-based workflow)
• -Projects requiring formal release branches (e.g., mobile apps with app store review)
• -Teams with no CI/CD pipeline (fix that first)