git-storytelling-branch-strategy

What this skill does

# Git Storytelling - Branch Strategy

This skill helps you implement effective branching strategies that tell the story of your development process through organized, purposeful branch management. Good branching creates a clear narrative of parallel development efforts.

## Core Concepts

### Why Branch Strategy Matters

A good branching strategy:

- **Creates clear development narratives** - Each branch tells a specific story
- **Enables parallel work** - Multiple features can develop simultaneously
- **Facilitates code review** - Changes are isolated and reviewable
- **Supports deployment workflows** - Different branches for different environments
- **Reduces merge conflicts** - Smaller, focused branches are easier to merge
- **Documents development history** - Branch names and structure show intent

### The Story of Branches

Think of branches as parallel storylines in your codebase:

- **Main branch**: The canonical story, always working and deployable
- **Feature branches**: Side quests that eventually merge into the main story
- **Release branches**: Chapters being prepared for publication
- **Hotfix branches**: Emergency patches to the published story
- **Development branch**: The staging area where stories come together

## Branch Naming Conventions

### Standard Prefixes

Use consistent prefixes to categorize branches:

```
feature/    - New features
fix/        - Bug fixes
hotfix/     - Production emergency fixes
refactor/   - Code refactoring
test/       - Testing changes
docs/       - Documentation
chore/      - Maintenance tasks
release/    - Release preparation
```

### Naming Best Practices

Good branch names are:

```bash
# GOOD: Clear, descriptive, kebab-case
feature/user-authentication
fix/payment-processing-timeout
refactor/extract-validation-logic
hotfix/critical-security-patch

# BAD: Vague, unclear, inconsistent
feature/new-stuff
fix-thing
my-branch
temp
```

### Including Issue Numbers

Reference tracking system issues:

```bash
feature/123-add-user-authentication
fix/456-resolve-memory-leak
hotfix/789-patch-security-vulnerability
```

### Branch Name Format

Follow a consistent pattern:

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

Examples:
feature/234-oauth-integration
fix/567-null-pointer-exception
refactor/890-simplify-error-handling
```

## Common Branching Strategies

### Git Flow

A robust branching model for release-based software:

```bash
# Main branches (permanent)
main        # Production-ready code
develop     # Integration branch for features

# Supporting branches (temporary)
feature/*   # New features
release/*   # Release preparation
hotfix/*    # Production fixes
```

**Git Flow Workflow:**

```bash
# Start new feature
git checkout develop
git checkout -b feature/user-profile

# Work on feature with commits
git commit -m "feat: add user profile model"
git commit -m "feat: add profile update endpoint"

# Finish feature
git checkout develop
git merge --no-ff feature/user-profile
git branch -d feature/user-profile

# Start release
git checkout develop
git checkout -b release/v1.2.0

# Prepare release
git commit -m "chore: bump version to 1.2.0"
git commit -m "docs: update CHANGELOG"

# Finish release
git checkout main
git merge --no-ff release/v1.2.0
git tag -a v1.2.0 -m "Release version 1.2.0"
git checkout develop
git merge --no-ff release/v1.2.0
git branch -d release/v1.2.0

# Emergency hotfix
git checkout main
git checkout -b hotfix/v1.2.1

# Fix and release
git commit -m "fix: critical security issue"
git checkout main
git merge --no-ff hotfix/v1.2.1
git tag -a v1.2.1 -m "Hotfix version 1.2.1"
git checkout develop
git merge --no-ff hotfix/v1.2.1
git branch -d hotfix/v1.2.1
```

### GitHub Flow

A simpler model for continuous deployment:

```bash
# Only one main branch
main        # Always deployable

# All work in feature branches
feature/*   # Features, fixes, everything
```

**GitHub Flow Workflow:**

```bash
# Create feature branch from main
git checkout main
git pull origin main
git checkout -b feature/add-search

# Make commits
git commit -m "feat: add search component"
git commit -m "test: add search tests"
git commit -m "docs: document search API"

# Push and create pull request
git push -u origin feature/add-search

# After review and CI passes, merge via PR
# Then deploy main branch

# Clean up
git checkout main
git pull origin main
git branch -d feature/add-search
```

### Trunk-Based Development

Minimal branching with short-lived feature branches:

```bash
# Main branch
main        # The trunk, always deployable

# Short-lived feature branches (< 1 day)
feature/*   # Small, quick features
```

**Trunk-Based Workflow:**

```bash
# Create short-lived feature branch
git checkout main
git pull origin main
git checkout -b feature/update-button-text

# Make focused change
git commit -m "feat: update CTA button text"

# Push and merge same day
git push -u origin feature/update-button-text

# Merge via PR or direct merge
git checkout main
git merge feature/update-button-text
git push origin main

# Delete branch immediately
git branch -d feature/update-button-text
```

### GitLab Flow

Environment branches for deployment stages:

```bash
# Main development branch
main              # Integration branch

# Environment branches
staging           # Staging environment
production        # Production environment

# Feature branches
feature/*         # Features merge to main
```

**GitLab Flow Workflow:**

```bash
# Develop feature
git checkout main
git checkout -b feature/notification-system
git commit -m "feat: add notification system"

# Merge to main
git checkout main
git merge feature/notification-system

# Deploy to staging
git checkout staging
git merge main
git push origin staging  # Triggers staging deployment

# After testing, deploy to production
git checkout production
git merge staging
git push origin production  # Triggers production deployment
```

## Code Examples

### Example 1: Starting a Feature Branch

```bash
# Update main branch
git checkout main
git pull origin main

# Create feature branch with descriptive name
git checkout -b feature/456-implement-two-factor-auth

# Verify you're on new branch
git branch --show-current
# Output: feature/456-implement-two-factor-auth

# Make initial commit
git commit --allow-empty -m "feat: initialize two-factor authentication feature"

# Push branch to remote
git push -u origin feature/456-implement-two-factor-auth

# Continue development
git commit -m "feat: add TOTP token generation"
git commit -m "feat: add token verification endpoint"
git commit -m "test: add 2FA integration tests"
```

### Example 2: Keeping Feature Branch Updated

```bash
# While working on feature branch, main has moved forward
git checkout feature/789-user-dashboard

# Option 1: Rebase (creates linear history)
git fetch origin
git rebase origin/main

# If conflicts occur
git status  # See conflicting files
# Fix conflicts in editor
git add .
git rebase --continue

# Option 2: Merge (preserves branch history)
git fetch origin
git merge origin/main

# Resolve any merge conflicts
git add .
git commit -m "merge: resolve conflicts with main"

# Push updated branch
git push --force-with-lease origin feature/789-user-dashboard
```

### Example 3: Release Branch Workflow

```bash
# Create release branch from develop
git checkout develop
git pull origin develop
git checkout -b release/v2.0.0

# Prepare release
git commit -m "chore: bump version to 2.0.0"
git commit -m "docs: update CHANGELOG for v2.0.0"
git commit -m "chore: update dependencies"

# Fix bugs found during release testing
git commit -m "fix: resolve edge case in user validation"
git commit -m "fix: correct API response format"

# Merge to main and tag
git checkout main
git merge --no-ff release/v2.0.0
git tag -a v2.0.0 -m "Release version 2.0.0

Major changes:
- New user authentication system
- Improved performance
- Updated API endpoints

See CHANGELOG.md for details."

# Merge back to develop
git checkout develop
git