Trunk-Based Development
debt(d7/e7/b7/t5)
Closest to 'only careful code review or runtime testing' (d7). The detection_hints note automated detection is 'no' and the code_pattern is 'Long-lived feature branches >1 week; complex merge ceremonies; large merge conflicts from diverged branches.' Tools listed (git, github, launchdarkly) can surface branch age metrics but require deliberate inspection — no tool automatically flags TBD violations. A team drifts away from TBD gradually and only careful process review or CI pain reveals it.
Closest to 'cross-cutting refactor across the codebase' (e7). The quick_fix describes a conceptually simple change (commit to main, use feature flags), but operationalizing TBD requires changing developer habits, branch policies, CI pipeline configuration, introducing feature flag infrastructure (e.g. LaunchDarkly), and updating team process across the entire organization. Common mistakes list multiple interrelated practices (feature flags, review culture, branch discipline) that all must change together — this is a cross-cutting, team-wide remediation.
Closest to 'strong gravitational pull' (e7, mapped to b7). TBD applies to all web and CLI contexts per applies_to, and its tags span devops, git, ci-cd, and team-process — meaning every developer, every feature, every deployment is shaped by this choice. Abandoning or adopting TBD reshapes how PRs, CI pipelines, feature releases, and hotfixes are managed. It exerts gravitational pull on every change made to the codebase.
Closest to 'notable trap — a documented gotcha most devs eventually learn' (t5). The misconception field explicitly states: 'Trunk-based development means committing untested code directly to main' — developers conflate TBD with cowboy coding or no-review workflows, when in fact it demands higher testing discipline and feature flags. This is a well-documented, common misunderstanding that misleads competent developers unfamiliar with the practice.
Also Known As
TL;DR
Explanation
Trunk-Based Development (TBD) requires developers to commit to the main branch at least once per day, keeping branches short-lived (hours, not weeks). This forces continuous integration — conflicts surface immediately rather than at merge time. Incomplete features are hidden behind feature flags. TBD reduces merge conflicts, improves team visibility, and enables true continuous deployment. It requires a comprehensive automated test suite and discipline around feature flags. Google, Facebook, and Netflix use variants of TBD at scale. It contrasts with GitFlow, where feature branches can live for weeks.
Common Misconception
Why It Matters
Common Mistakes
- Feature branches that live longer than 1-2 days — divergence makes merges painful.
- Not using feature flags to hide incomplete work — trunk-based requires deploying incomplete features safely.
- Skipping code review for small changes — small changes still need review; pair programming is an alternative.
- Confusing trunk-based development with no branching — short-lived branches are fine; long-lived ones are not.
Code Examples
# Long-lived feature branch — anti-pattern:
git checkout -b feature/new-payment-system
# 6 weeks of development
# 847 files changed
# Merge conflict hell with main
# Trunk-based:
git checkout -b feature/payment-step-1 # 1 day max
# Small, releasable increment behind a feature flag
git merge main # Easy — only 1 day of divergence# Trunk-based: all devs commit to main (or short-lived branches <1 day)
# Feature in progress but not ready → hide behind a flag
# 1. Create branch, work, push small commits daily
git checkout -b feat/new-checkout
# 2. Merge to main within a day — feature flag hides incomplete work
git checkout main && git merge feat/new-checkout
# Feature flag keeps it off for users until complete
if ($this->flags->isEnabled('new_checkout', $user)) {
return $this->newCheckout->handle($cart);
}
return $this->legacyCheckout->handle($cart);
# CI runs on every push to main — must stay green
# If you break main, fix forward or revert immediately