# Branch Strategy Quick Reference

## Workflow Diagram

```
main (trunk) ─────────────●─────●─────●─────●──── (tags: v0.3.0, v0.4.0)
                          │     │     │     │
                          │     │     │     └─ feature/unc-paths ──┐
                          │     │     └─ fix/race-condition ───────┤
                          │     └─ patch/update-docs ──────────────┤
                          └─ feature/long-paths ───────────────────┘
                                                                    │
                                                              (merge via PR)
```

## Branch Naming

```bash
feature/<description>    # New functionality → Minor bump (0.x.0)
fix/<description>        # Bug fixes → Patch bump (0.0.x)
patch/<description>      # Documentation, typos → Patch bump (0.0.x)
chore/<description>      # Maintenance → Patch bump (0.0.x)
refactor/<description>   # Code restructuring → Patch bump (0.0.x)
perf/<description>       # Performance → Minor bump (0.x.0)
breaking/<description>   # Breaking changes → Major bump (x.0.0)
hotfix/<description>     # Emergency fixes from tag → Patch bump (0.0.x)
```

## Release Workflow

### Regular Release

```bash
# 1. Ensure on main
git checkout main
git pull

# 2. Bump version in pyproject.toml and CHANGELOG.md
# 3. Commit
git commit -m "chore: bump version to 0.4.0"

# 4. Tag (ONLY from main)
git tag -a v0.4.0 -m "Version 0.4.0: Summary"

# 5. Push
git push origin main
git push origin v0.4.0

# 6. GitHub Actions auto-publishes to PyPI
```

### Hotfix

```bash
# 1. Branch from tag
git checkout v0.3.0
git checkout -b hotfix/critical-fix

# 2. Fix and commit
git commit -m "fix: critical security patch"

# 3. Bump version (0.3.0 → 0.3.1)
git commit -m "chore: bump version to 0.3.1"

# 4. Merge to main
git checkout main
git merge --no-ff hotfix/critical-fix

# 5. Tag
git tag -a v0.3.1 -m "Hotfix 0.3.1"

# 6. Push
git push origin main v0.3.1
```

## Semantic Versioning

```
MAJOR.MINOR.PATCH
  │     │      └─ Bug fixes, docs, internal refactors
  │     └──────── New features, backwards-compatible
  └────────────── Breaking changes

Examples:
  0.3.0 → 0.3.1   # Bug fix
  0.3.1 → 0.4.0   # New feature
  0.4.0 → 1.0.0   # Breaking change or stable release
```

## Commit Convention

```bash
<type>(<scope>): <subject>

Types:
  feat:     New feature
  fix:      Bug fix
  docs:     Documentation
  style:    Formatting
  refactor: Code restructuring
  perf:     Performance
  test:     Tests
  chore:    Maintenance
  ci:       CI/CD
  revert:   Revert previous commit

Examples:
  feat(cli): add --force-symlink flag
  fix(install): handle Windows long paths
  docs: update installation instructions
  chore: bump version to 0.4.0
```

## Common Tasks

### Start New Feature

```bash
git checkout main
git pull
git checkout -b feature/my-feature
# ... work ...
git push -u origin feature/my-feature
# Create PR on GitHub
```

### Update Feature Branch

```bash
git checkout main
git pull
git checkout feature/my-feature
git rebase main  # or: git merge main
git push --force-with-lease
```

### Squash Commits Before Merge

```bash
# Interactive rebase
git rebase -i main

# Or use GitHub's "Squash and merge" button
```

## Protection Rules

**main branch:**
- Require PR for all changes
- Require review approval
- Require status checks to pass
- No direct pushes (except version bumps)
- No force pushes

**Tags:**
- Only from main branch
- Must follow v*.*.* format
- Must match pyproject.toml version
- Triggers automated release

## Quick Checks

Before creating PR:
```bash
make test              # Run tests
ruff check src/ tests/ # Lint
ruff format src/ tests/# Format
mypy src/              # Type check
```

Before tagging:
```bash
git log v0.3.0..HEAD --oneline  # Review commits
make test                       # Full test suite
make build                      # Test build
```

## See Also

- [CONTRIBUTING.md](../CONTRIBUTING.md) - Full contribution guidelines
- [CHANGELOG.md](../CHANGELOG.md) - Version history
- [.github/workflows/](.workflows/) - CI/CD automation
