Recap — Picking a Strategy by Team Size and Cadence

# Picking a Strategy by Team Size and Cadence Three dominant branching strategies. None is universally best; choose by your team's constraints. ## Trunk-Based Development One main branch (trunk / main). Short-lived feature branches (hours or a day). Frequent merges. ``` main: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ↓ ↑ ↓ ↑ ↓ ↑ short feature branches (live ~1 day) ``` Practices: - Feature branches live 1-2 days max. - Tiny PRs, fast review, fast merge. - Feature flags hide incomplete features. - CI runs on every commit; broken = highest priority fix. When it works: - High-velocity teams. - Mature CI/CD; deploys are routine. - Feature flag infrastructure. - Strong test coverage. Examples: Google, Facebook, modern web companies. Pros: - Always-deployable trunk. - Low merge conflicts (small windows). - Continuous integration in spirit. Cons: - Requires discipline (small PRs, fast review). - Without feature flags, exposes incomplete work. - Doesn't scale to large teams without good infra. ## GitHub Flow A simplified version of trunk-based. Main + feature branches. Each merge to main is deployable. ``` main: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ↑ ↑ ↑ feature feature feature ``` Practices: - Branch from main. - Open PR when ready (or as draft for WIP). - Review + merge. - Deploy from main continuously OR after manual trigger. When it works: - Web apps, SaaS. - Small to medium teams. - Continuous deploy or daily releases. This is the default for most modern open-source and SaaS projects. Pros: - Simple; minimal ceremony. - Encourages CI/CD. - Easy to onboard new contributors. Cons: - Doesn't model formal releases. - Not great for codebases with multiple maintained versions (e.g., libraries with v1, v2, v3 all supported). ## GitFlow Multi-branch model with main, develop, feature, release, and hotfix branches. ``` main: ━━━━━━━━━━━━━━━━━━━━━━━ (production) ↑ ↑ ↑ ↑ release release release hotfix / develop: ━━━━━━━━━━━━━━━━━━━━━━━ (integration) ↑ ↑ ↑ feature feature feature ``` Branches: - **main**: production code; tagged with versions. - **develop**: integration of features; deployed to staging. - **feature/X**: new features; merged into develop. - **release/X.Y**: prepping a release (final testing, version bumps). - **hotfix/X**: urgent production fixes; merge to both main and develop. When it works: - Versioned products (libraries, packaged software, mobile apps). - Formal release schedules (every 2 weeks, monthly). - Multiple supported versions in parallel. When it's overkill: - Web app with continuous deploy. Way too much process. - Small teams. Branching overhead > benefit. Pros: - Clear separation of in-progress vs production. - Supports multiple parallel releases. - Hotfix path is explicit. Cons: - Complex; lots of branches; many merges. - Doesn't fit continuous deploy. - Long-lived branches → big merge conflicts. In 2026, GitFlow has fallen out of fashion for SaaS; still common in some enterprise / packaged-software contexts. ## Decision matrix | Context | Strategy | |---|---| | Modern SaaS / web app | GitHub Flow | | High-velocity FAANG-style | Trunk-Based + Feature Flags | | Versioned library / packaged software | GitFlow OR GitHub Flow with release branches | | Open source project | GitHub Flow | | Mobile app (App Store releases) | GitFlow-lite (with release branches) | ## Hybrid: GitHub Flow with release branches Many teams: GitHub Flow most of the time + a release branch for stable versions. ``` main: ━━━━━━━━━━━━━━━━━━━━━━━ (always-deployable) release/v1.5: ━━━━━━━━━━━ (current production release) ``` When v1.6 is released, cut a new release/v1.6 branch. Useful for: maintaining old versions while continuing main. ## Feature flags — the trunk-based enabler Feature flags wrap incomplete code: ```python if feature_flags.is_enabled("new_search"): return new_search_impl() else: return old_search_impl() ``` Allows merging incomplete features into main safely. Flag toggles in production control rollout. Tools: LaunchDarkly, GrowthBook, GitHub's own (or roll your own with config). ## Common branching mistakes 1. **GitFlow on a small team.** Process overhead exceeds benefit. 2. **Long-lived branches.** Merge conflicts compound over time. 3. **No clear rule for what goes to which branch.** Confusion. 4. **Releasing from main with WIP.** Need feature flags or proper releases. 5. **Mixing strategies.** "Sometimes trunk, sometimes GitFlow." Pick one. ## Migration paths GitFlow → GitHub Flow: many teams have done this. Steps: - Merge develop into main. - Delete develop. - Make main always-deployable (cut releases on a branch). - Update team docs. GitHub Flow → Trunk-based: enable feature flags; tighten review-to-merge cycle; aim for <1-day feature branches. ## Branching strategy docs Document yours in `CONTRIBUTING.md`: ```markdown # Branching strategy We us