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: /-
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, -
  fix/-
  hotfix/-
  release/v
  chore/-

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: VersoXBT
• Source: VersoXBT/claude-initial-setup
• License: MIT
• Homepage: https://github.com/VersoXBT/claude-initial-setup#installation

Install and usage instructions live in the source repository linked above.