git-branching-strategy

What this skill does

# Git Branching Strategy

Prevent monster branches by following disciplined branching and merge practices.

## When to Use This Skill

Invoke this skill when:

### ✅ Starting New Work
- About to implement a new feature
- Planning to fix a bug
- Starting refactoring work
- Adding documentation

### ⚠️ Mid-Feature Warning Signs
- Thinking "while I'm here, I'll also..."
- Wanting to add unrelated functionality
- Branch has grown beyond 20 commits
- Multiple unrelated files changed
- Changes would be difficult to understand

### 🎯 Decision Points
- Unsure whether to create new branch or continue current
- Wondering if branch is getting too large
- Considering adding "just one more thing"
- Ready to merge but branch feels messy

---

## ⚠️ Pre-Implementation Checklist

**BEFORE writing ANY code, answer these questions:**

### 1. Is this non-trivial work?

**Non-trivial = ANY of these:**
- ✅ Changes **>2 files**
- ✅ Refactoring existing code
- ✅ Adding new features/functionality
- ✅ Implementing planned tasks
- ✅ Bug fixes requiring changes to multiple components

**Trivial = ALL of these:**
- ❌ Fixing typo in single file
- ❌ Updating documentation only (markdown, comments)
- ❌ One-line fix in single file

### 2. If Non-Trivial → CREATE FEATURE BRANCH

```bash
# Ensure main branch is up to date
git checkout main
git pull origin main

# Create feature branch (choose appropriate prefix)
git checkout -b feature/descriptive-name    # For new features
git checkout -b refactor/descriptive-name   # For refactoring
git checkout -b fix/descriptive-name        # For bug fixes
```

**Examples:**
- `feature/user-authentication` - New auth implementation
- `refactor/error-handling` - Standardize error handling
- `fix/login-redirect` - Fix login redirect bug

### 3. Golden Rule

**When in doubt, use a feature branch.**

Feature branches provide:
- 📝 Documentation of what changed and why
- 📊 Clear history of feature development
- 🔄 Easy to revert if needed
- 🧪 Isolated testing before merge

---

## The Problem: Monster Branches

### What Happens

**Timeline:**
- Started as "add feature X"
- Grew to include features Y, Z, refactoring, and bug fixes
- **100+ commits**, multiple intertwined features
- Difficult to review, hard to merge, risky to revert

**Symptoms:**
- ❌ Multiple distinct features mixed together
- ❌ Hard to describe what the branch does in one sentence
- ❌ Changes span unrelated systems
- ❌ Commit history is difficult to follow
- ❌ Rolling back one feature means losing others

**Consequences:**
- Long-lived branch diverges from main
- Merge conflicts accumulate
- Testing becomes all-or-nothing
- Can't ship features incrementally
- Hard to isolate bugs introduced

## Solution: Small, Focused Branches

### The Golden Rule

**One feature, one branch, one merge.**

If you can't describe the branch in a single sentence without using "and", it's too big.

### Good Examples

✅ **Good:** `feat/user-auth` - "Add basic user authentication"
✅ **Good:** `feat/smart-fields` - "Implement smart field system"
✅ **Good:** `fix/race-condition` - "Fix optimistic update race condition"
✅ **Good:** `refactor/scss-modules` - "Convert SCSS to module system"
✅ **Good:** `docs/contributing` - "Add contributing guidelines"

### Bad Examples

❌ **Bad:** `feat/improvements` - Too vague, likely includes unrelated changes
❌ **Bad:** `fix/various-bugs` - Multiple unrelated fixes should be separate branches
❌ **Bad:** `wip/stuff` - Not descriptive, suggests unfocused work

## Branch Size Guidelines

### Target Size

**Ideal:** 5-15 commits, 1-5 files changed significantly
**Acceptable:** Up to 30 commits, up to 10 files
**Too Large:** 50+ commits, 20+ files

**Exception:** Large refactors that are purely mechanical

### Commit Count Checkpoints

```
5 commits → Normal feature pace
10 commits → Check: Am I still focused on one feature?
20 commits → WARNING: Consider splitting or wrapping up
30 commits → CRITICAL: Finish and merge, or split into multiple branches
50+ commits → MONSTER: This should have been 3-5 separate branches
```

### When Branch Size is Justified

✅ **Acceptable large branches:**
- Pure refactoring (converting styles, modularization)
- Data migrations (changing structure across many files)
- Framework version upgrades (mechanical API changes)
- Initial feature implementation with tests and docs

❌ **Unacceptable large branches:**
- Multiple unrelated features
- Feature + "while I'm here" improvements
- Feature + unrelated bug fixes
- Feature + refactoring that isn't required for feature

## Decision Tree: New Branch or Continue?

### Question 1: Is this change related to current branch?

```
New change → Related to current feature?
  ↓ YES (same system, same goal)
  → Continue current branch

  ↓ NO (different system, different goal)
  → Question 2
```

### Question 2: Is current branch ready to merge?

```
Current branch → Ready to merge?
  ↓ YES (feature complete, tests pass)
  → Merge current, then new branch for new work

  ↓ NO (feature incomplete)
  → Question 3
```

### Question 3: Is new work required for current feature?

```
New work → Required for current feature to work?
  ↓ YES (dependency)
  → Continue current branch

  ↓ NO (nice-to-have, improvement, unrelated)
  → Stash current, new branch, finish new, resume current
```

## Branch Naming Conventions

### Format

```
<type>/<short-description>
```

### Types

- **feat/** - New feature or enhancement
- **fix/** - Bug fix
- **refactor/** - Code restructuring without behavior change
- **docs/** - Documentation only
- **test/** - Adding or fixing tests
- **chore/** - Build, tooling, dependencies

### Examples

```
feat/user-auth
feat/smart-fields
feat/dashboard
fix/login-redirect
fix/memory-leak
refactor/scss-modules
refactor/modularization
docs/contributing
docs/api-guide
chore/update-deps
```

### Avoid

❌ `feature/` - Use `feat/` (shorter)
❌ `bugfix/` - Use `fix/` (shorter)
❌ `wip/` - Work in progress is implied, use descriptive name
❌ `my-branch` - Not descriptive
❌ `feat/add-feature` - Redundant "add"

## Branch Lifecycle

### 1. Plan and Scope

**Before creating branch:**
- [ ] Can I describe this in one sentence?
- [ ] Is this the smallest useful increment?
- [ ] Does this depend on other incomplete work?
- [ ] Will this take more than 30 commits?

**If >30 commits expected:** Break into smaller features first.

### 2. Create Branch

```bash
# From main (or integration branch)
git checkout main
git pull origin main

# Create feature branch
git checkout -b feat/descriptive-name
```

### 3. Work on Feature

**Commit discipline:**
- Small, focused commits
- Clear commit messages
- Commit related changes together
- Don't mix formatting with logic changes

**Check progress regularly:**
```bash
# How many commits?
git log main..HEAD --oneline | wc -l

# How many files changed?
git diff main --stat

# Am I still focused?
git log --oneline -10  # Review recent commits
```

### 4. Recognize When to Split

**Warning signs:**
- Commit messages use "and" frequently
- Multiple unrelated `// TODO` comments
- You've forgotten what early commits did
- Summary of changes needs 3+ bullet points for unrelated changes

**How to split:**

```bash
# Option A: Finish current, branch for next
git commit -m "Complete X feature"
# Merge feat/x
git checkout -b feat/y  # Start next feature

# Option B: Stash incomplete, branch for urgent work
git stash
git checkout -b fix/urgent-bug
# Fix and merge
git checkout feat/original
git stash pop
```

### 5. Prepare for Merge

**Before merging:**
```bash
# Rebase on latest main
git fetch origin
git rebase origin/main

# Review all changes
git diff origin/main

# Check commit history is clean
git log origin/main..HEAD --oneline

# Run tests if applicable
npm test  # or your test command
```

### 6. Merge to Main

```bash
# Switch to main and merge
git checkout main
git pull origin main
git merge --no-ff feat/descriptive-name

# Push to remote
git push origin main

# Delete local