branching-strategy

Branching Strategy

Choose and apply the right branching model for the project's size, team, and release cadence.

When to Use

• Creating a new branch for a feature, fix, or release
• Deciding between merge and rebase
• Setting up a new repository's branching conventions
• Discussing release management and deployment strategies
• Resolving merge conflicts or untangling branch history

Core Patterns

Branch Naming Conventions

Use a consistent prefix/slug format:

# Format: <type>/<ticket-id>-<short-description>
feature/AUTH-123-add-sso-login
fix/BUG-456-null-pointer-on-logout
refactor/TECH-789-extract-auth-service
hotfix/SEC-101-patch-xss-vulnerability
release/v2.3.0
chore/TECH-202-upgrade-node-20

# Without ticket system
feature/add-user-registration
fix/prevent-race-condition-in-cache

Rules:

• Lowercase with hyphens (kebab-case)
• Keep under 50 characters after the prefix
• Include ticket ID when available
• Use descriptive slugs, not cryptic abbreviations

Git Flow (Structured Releases)

Best for: projects with scheduled releases, multiple environments, or compliance requirements.

main ────────●────────────────●──────────── (production)
              \              /
release/v2.1   ●────●──────●               (stabilization)
              /      \
develop ────●────●────●────●────●────────── (integration)
            \        /          \
feature/x    ●──●──●            \
                                 \
feature/y                         ●──●──●

# Start a feature
git checkout develop
git checkout -b feature/AUTH-123-add-sso

# Complete a feature — merge back to develop
git checkout develop
git merge --no-ff feature/AUTH-123-add-sso
git branch -d feature/AUTH-123-add-sso

# Create a release branch
git checkout develop
git checkout -b release/v2.1.0

# Finalize release
git checkout main
git merge --no-ff release/v2.1.0
git tag -a v2.1.0 -m "Release v2.1.0"
git checkout develop
git merge --no-ff release/v2.1.0

# Hotfix from production
git checkout main
git checkout -b hotfix/SEC-101-patch-xss
# ... fix applied ...
git checkout main
git merge --no-ff hotfix/SEC-101-patch-xss
git tag -a v2.1.1 -m "Hotfix v2.1.1"
git checkout develop
git merge --no-ff hotfix/SEC-101-patch-xss

Trunk-Based Development (Continuous Delivery)

Best for: small teams, CI/CD pipelines, frequent deployments.

main ──●──●──●──●──●──●──●──●──●── (always deployable)
        \   /  \   /      \   /
         ●─●    ●─●        ●─●     (short-lived branches, <2 days)

# Short-lived feature branch
git checkout main
git pull --rebase origin main
git checkout -b feature/add-search

# Keep branch fresh (daily)
git fetch origin
git rebase origin/main

# Merge back quickly (within 1-2 days)
git checkout main
git merge --no-ff feature/add-search
git push origin main

Key rules for trunk-based:

• Branches live less than 2 days
• Feature flags for incomplete work
• Main is always deployable
• No long-lived branches except main

Merge vs Rebase Decision

# REBASE: Use for local branch cleanup before merging
# Produces linear history, easier to read
git checkout feature/my-work
git rebase main
git checkout main
git merge --no-ff feature/my-work

# MERGE: Use for integrating shared/public branches
# Preserves full history and merge points
git checkout main
git merge --no-ff feature/my-work

# SQUASH MERGE: Use for PRs with messy intermediate commits
# Produces single clean commit on target branch
git checkout main
git merge --squash feature/my-work
git commit -m "feat: add search functionality"

Strategy	When to Use	Trade-off
Merge	Shared branches, preserving history	Noisy log, but full context
Rebase	Local cleanup, linear history	Clean log, rewrites history
Squash	Messy PR history, single logical unit	Cleanest log, loses details

Golden rule: Never rebase commits that have been pushed to a shared branch.

Anti-Patterns

What NOT to Do

• Long-lived feature branches: Branches open for weeks accumulate merge conflicts and drift from main. Keep branches short-lived.
• Committing directly to main: Even solo developers benefit from branch-based workflow for rollback safety.
• Rebasing shared branches: Rewriting history on branches others work on causes lost commits and confusion.
• Inconsistent naming: Mixing feature/, feat/, Feature/, and no prefix makes automation and filtering impossible.
• No branch protection: Main/develop should require PR reviews and CI checks. Never force-push to protected branches.

# BAD: Direct commit to main
git checkout main
git commit -m "feat: add new feature"
git push

# BAD: Rebase a shared branch
git checkout develop
git rebase main  # Others are also working on develop!

# GOOD: Feature branch with PR
git checkout -b feature/add-search
# ... work ...
# Open PR, get review, merge via PR

Quick Reference

Branch Naming:
  feature/<ticket>-<description>
  fix/<ticket>-<description>
  hotfix/<ticket>-<description>
  release/v<semver>
  chore/<ticket>-<description>

Strategy Selection:
  Scheduled releases + multiple envs  -> Git Flow
  Continuous delivery + small team    -> Trunk-based
  Open source + many contributors     -> GitHub Flow (fork + PR)

Merge Strategy:
  Local cleanup         -> rebase then merge --no-ff
  Shared branch         -> merge --no-ff (never rebase)
  Messy PR commits      -> squash merge

Rules:
  - Never rebase public/shared branches
  - Never force-push to main or develop
  - Keep feature branches under 2 days (trunk-based)
  - Always use --no-ff for merge commits (preserves branch history)
  - Delete branches after merging