Branch Strategy Guide

A comprehensive guide for choosing the right branch protection and workflow strategy for development projects.

Quick Decision Tree

Step 1: Team Size

• Solo developer (1) - Option 1 or Direct Push
• Small team (2-4) - Option 1 or Option 2
• Medium team (5-10) - Option 2 or Option 3
• Large team (10+) - Option 3 or Option 4

Step 2: Project Complexity

• Documentation/Simple - Option 1 or 2
• Standard Web Development - Option 2 or 3
• Complex Applications - Option 3 or 4
• Enterprise/Multi-Environment - Option 4

Step 3: Release Requirements

• Continuous deployment - Option 1 or 2
• Weekly/Sprint releases - Option 2 or 3
• Formal release cycles - Option 3 or 4
• Multiple environments - Option 4

---

Branch Strategy Options

Option 0: No Protection (Not Recommended)

Setup: No branch protection rules

When to consider:

• Solo developer on personal projects
• Throwaway/prototype projects
• Very experienced developers with strong discipline

Risks:

• Accidental direct commits to main
• No change history or review process
• Difficult to revert problematic changes

Avoid This Approach

Even solo developers benefit from PR workflow for history and rollback capability.

---

Option 1: Self-Merge (Basic Protection)

Best for: Small teams (1-4 people), rapid development, documentation projects

GitHub Settings

Branch Protection Rules (main):
  Require pull request before merging: true
    Required approvals: 0
    Dismiss stale reviews: false
    Require code owner review: false
    Allow bypass for admins: true
  Require status checks: false
  Require signed commits: false

Workflow

# Create feature branch
git checkout -b dev/feature-name
git push -u origin dev/feature-name

# Create and immediately merge PR
gh pr create --title "Add feature" --body "Description"
gh pr merge --squash  # Can self-approve

Advantages

• Fast development - No waiting for reviews
• Safety net - Prevents accidental main commits
• Clean history - All changes via PRs
• Emergency escape - Admin bypass available

Limitations

• No code review - Quality depends on individual discipline
• No collaboration checks - Can break shared code

---

Option 2: AI-Assisted Review

Best for: Small to medium teams wanting quality checks with speed

GitHub Settings

Branch Protection Rules (main):
  Require pull request before merging: true
    Required approvals: 0
    Allow bypass for admins: true
  Require status checks: true
    Require branches to be up to date: false
    Status checks required:
      - ai-code-review
      - lint
      - build

AI Review Integration

Add to .github/workflows/ai-review.yml:

name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: AI Review
        uses: coderabbitai/ai-pr-reviewer@latest
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}

Advantages

• Automated quality checks - AI catches common issues
• Fast feedback - No waiting for human review
• Educational - AI explanations help learning
• Consistent - Same review standards always applied

---

Option 3: Staging Branch Workflow

Best for: Medium teams with QA requirements

Branch Structure

main (production)
  └── staging (pre-production)
       └── feature branches

GitHub Settings

Branch Protection (main):
  Require pull request: true
  Required approvals: 1
  Require status checks: true
    Required: staging-deploy, e2e-tests

Branch Protection (staging):
  Require pull request: true
  Required approvals: 0
  Require status checks: true
    Required: lint, build, unit-tests

Workflow

# Feature development
git checkout staging
git checkout -b feature/new-feature

# Merge to staging
gh pr create --base staging
# After review and merge, deploy to staging

# Promote to production
gh pr create --base main --head staging
# Requires approval and passing E2E tests

---

Option 4: Git Flow (Enterprise)

Best for: Large teams, formal releases, multiple environments

Branch Structure

main (production)
├── develop (integration)
│   └── feature/* (new features)
├── release/* (release preparation)
└── hotfix/* (emergency fixes)

Workflow

1. Features branch from develop
2. Features merge back to develop
3. Release branches created from develop
4. Release merges to both main and develop
5. Hotfixes branch from main, merge to both

---

Branch Naming Convention

Standard Format

{type}/{ticket-id}/{brief-description}

Examples

# Features
feature/FLY-123/user-authentication
feature/FLY-456/shopping-cart

# Bug fixes
fix/FLY-789/login-redirect-issue
bugfix/FLY-012/cart-total-calculation

# Hotfixes
hotfix/FLY-345/security-patch

# Documentation
docs/FLY-678/api-documentation

# Refactoring
refactor/FLY-901/cleanup-auth-module

Developer Initials (Optional)

For smaller teams:

ml/FLY-123/user-authentication
jd/FLY-456/shopping-cart

---

Commit Message Standards

Format

type(scope): brief description

[optional body]

[optional footer]

Types

• feat - New feature
• fix - Bug fix
• docs - Documentation only
• style - Formatting, no code change
• refactor - Code restructuring
• test - Adding tests
• chore - Maintenance tasks

Examples

feat(auth): add password reset functionality

Implements password reset flow with email verification.
- Add reset password API endpoint
- Add email template for reset link
- Add password reset form component

Closes FLY-123

---

fix(cart): correct total calculation with discounts

The cart total was not including discount codes properly.
This fix ensures discounts are applied before tax calculation.

Fixes FLY-456

---

Recommendation Summary

Scenario	Recommended Option
Solo/Documentation	Option 1 (Self-Merge)
Small Team (2-4)	Option 2 (AI-Assisted)
Medium Team with QA	Option 3 (Staging)
Enterprise/Formal	Option 4 (Git Flow)
FLYPILOT Default	Option 2

FLYPILOT Standard

Most FLYPILOT projects use Option 2 (AI-Assisted Review) for the balance of speed and quality. Upgrade to Option 3 when project complexity warrants it.