StarPunk/docs/decisions/ADR-009-git-branching-strategy.md

# ADR-009: Git Branching Strategy

## Status

Accepted

## Context

StarPunk needs a git branching strategy that supports:

1. **Semantic versioning workflow** - Moving from 0.x.y development through 1.0.0 stable release
2. **Single developer initially** - Optimized for solo work but scalable to small teams
3. **Clean release history** - Clear tags and versioning aligned with SemVer
4. **Hotfix capability** - Ability to patch production releases
5. **Minimal complexity** - Appropriate for indie project scale
6. **Development discipline** - Structure without bureaucracy

### Current State

The project just renamed its primary branch from `master` to `main` to align with modern Git conventions and industry best practices. This is a brand new repository with no commits yet, currently at version 0.1.0 (development phase).

### Requirements

The branching strategy must:

1. **Support semantic versioning** releases (0.1.0 → 1.0.0 → 1.0.1 → 1.1.0 → 2.0.0)
2. **Work for solo and team** development
3. **Enable clean releases** with proper tagging
4. **Allow hotfixes** to production versions
5. **Keep main branch stable** - always in working state
6. **Minimize long-lived branches** - integrate frequently
7. **Align with IndieWeb values** - simplicity, no lock-in
8. **Be well-documented** - clear workflows for common scenarios

## Decision

We will adopt a **simplified trunk-based development** strategy with feature branches and semantic versioning integration.

### Core Principles

1. **Single primary branch**: `main`
2. **Branch name**: `main` (not `master`)
3. **Feature branches**: Short-lived branches for features/fixes
4. **Direct tagging**: Tag `main` for releases
5. **Hotfix branches**: For production patches (post-1.0.0)
6. **No long-lived branches**: Integrate to main frequently
7. **Annotated tags**: Always use annotated tags for releases

### Branch Structure

**Primary branch**: `main`
- Single source of truth
- Always stable (tests pass)
- Tagged for releases
- Protected from force push
- Never rewritten

**Feature branches**: `feature/<description>` or `<description>`
- Branch from `main`
- Merge into `main`
- Short-lived (hours to days, not weeks)
- Deleted after merge

**Fix branches**: `fix/<description>` or `bugfix/<description>`
- Branch from `main`
- Merge into `main`
- Deleted after merge

**Hotfix branches**: `hotfix/<version>-<description>` (post-1.0.0 only)
- Branch from release tag (e.g., `v1.0.0`)
- Fix critical production bugs
- Tagged as new patch release (e.g., `v1.0.1`)
- Merged into `main`
- Deleted after release

**Release branches**: `release/<version>` (optional, rarely used)
- Only if release preparation requires multiple commits
- For V1, likely unnecessary (prepare on `main` or feature branch)
- Branch from `main`, merge back to `main`, tag, delete

### Branch Naming Conventions

**Preferred format**: `<type>/<description>`

**Types**:
- `feature/` - New features
- `fix/` or `bugfix/` - Bug fixes
- `hotfix/` - Production hotfixes
- `docs/` - Documentation only
- `refactor/` - Code refactoring
- `test/` - Test additions
- `chore/` - Maintenance tasks

**Description**:
- Lowercase with hyphens
- Descriptive but concise
- Example: `feature/micropub-endpoint`, `fix/rss-timezone`

**Alternative**: Simple description without prefix (e.g., `micropub-endpoint`)

### Tagging Strategy

**Format**: `vMAJOR.MINOR.PATCH[-PRERELEASE]`

**Type**: Annotated tags (always)

**Examples**:
- `v0.1.0` - Development release
- `v1.0.0` - First stable release
- `v1.0.1` - Patch release
- `v1.0.0-alpha.1` - Pre-release

**Tag message format**:
```
Release MAJOR.MINOR.PATCH: <Brief description>

[Optional details]
```

### Workflows

**Development (0.x.y)**:
1. Work on `main` or feature branches
2. Commit frequently
3. Tag development milestones (v0.1.0, v0.2.0)
4. Breaking changes allowed

**Stable releases (1.0.0+)**:
1. Prepare release on `main`
2. Update version and changelog
3. Commit version bump
4. Create annotated tag
5. Push main and tag

**Hotfixes (post-1.0.0)**:
1. Branch from release tag
2. Fix bug
3. Update version and changelog
4. Tag new patch version
5. Merge to `main`
6. Push main and tag
7. Delete hotfix branch

## Rationale

### Why Simplified Trunk-Based Development?

**Trunk-based development** means developers integrate to a single branch (`main`) frequently, using short-lived feature branches.

**Pros**:
1. **Simple** - One primary branch, minimal overhead
2. **Scalable** - Works for solo and small teams
3. **Fast integration** - Reduces merge conflicts
4. **Always releasable** - Main stays stable
5. **Aligns with CI/CD** - Easy to automate testing
6. **Reduces complexity** - No long-lived branches to manage

**Fits StarPunk because**:
- Personal project optimized for simplicity
- Small codebase, infrequent releases
- Solo developer initially
- No need for complex branching

### Why Main Instead of Master?

**Decision**: Use `main` as primary branch name

**Rationale**:
1. **Industry standard** - GitHub, GitLab default since 2020
2. **Inclusive language** - Removes potentially offensive terminology
3. **Aligns with modern practices** - Most new projects use `main`
4. **Clear semantics** - "Main" clearly indicates primary branch
5. **No functional difference** - Just a name, but better name

**Migration**:
- Project just renamed `master` → `main`
- All documentation uses `main` consistently

### Why Not Git Flow?

**Git Flow** is a popular branching model with `main`, `develop`, `release`, `hotfix`, and `feature` branches.

**Considered but rejected**:

**Pros**:
- Well-defined process
- Clear separation of development and production
- Structured release process

**Cons**:
- **Too complex** for indie project
- **Overhead** - Multiple long-lived branches
- **Slow integration** - Features merge to develop, not main
- **Designed for** scheduled releases, not continuous delivery
- **Overkill** for single developer

**Conclusion**: Git Flow's complexity doesn't justify benefits for StarPunk's scale

### Why Not GitHub Flow?

**GitHub Flow** is a simpler model: just `main` and feature branches, deploy from `main`.

**Very close to our choice**:

**Pros**:
- Simple - only `main` + feature branches
- Fast - deploy anytime
- Works well with pull requests

**Differences from our approach**:
- GitHub Flow deploys directly from `main`
- We tag releases on `main` instead
- We add hotfix branches for production patches

**Conclusion**: We essentially use GitHub Flow + semantic versioning + hotfix branches

### Why Annotated Tags?

**Annotated vs lightweight tags**:

**Annotated tags** (chosen):
- Contain metadata (tagger, date, message)
- Can include release notes
- Can be GPG signed
- Treated as full Git objects
- Required: `git tag -a v1.0.0 -m "Release 1.0.0"`

**Lightweight tags** (rejected):
- Just pointers to commits
- No metadata
- Created: `git tag v1.0.0`

**Decision**: Always use annotated tags for releases
- Provides complete release history
- Can include release notes in tag message
- Better for professional releases

### Why Feature Branches?

**Alternatives**:
1. **Direct commits to main** - Fast but risky
2. **Feature branches** - Slight overhead but safer
3. **Pull request workflow** - Most structured

**Decision**: Use feature branches with flexible merge approach

**For solo development**:
- Feature branches optional for small changes
- Required for larger features
- Merge directly without pull request

**For team development**:
- Feature branches required
- Pull request review before merge
- Delete branch after merge

**Benefits**:
- Isolates work in progress
- Enables experimentation
- Keeps main stable
- Scalable to team workflow

## Consequences

### Positive

1. **Simple to understand** - One primary branch, clear workflows
2. **Scalable** - Works solo, scales to small teams
3. **Fast integration** - Short-lived branches reduce conflicts
4. **Clean history** - Clear tags for every release
5. **Semantic versioning alignment** - Tag strategy matches SemVer
6. **Hotfix capability** - Can patch production releases
7. **Low overhead** - No complex branch management
8. **Standard practices** - Uses modern Git conventions
9. **Well-documented** - Clear workflows for common scenarios
10. **Flexible** - Can use pull requests or direct merges

### Negative

1. **Discipline required** - Main must stay stable (tests must pass)
2. **Manual version management** - Must update version, changelog, tag (for V1)
3. **Solo optimization** - Strategy favors individual over large team
4. **No develop buffer** - Changes go directly to main (requires good testing)

### Neutral

1. **Feature branch discipline** - Must keep branches short-lived
2. **Test coverage important** - Main stability depends on testing
3. **Rebase vs merge** - Team must choose and be consistent

### Mitigations

**For main stability**:
- Run tests before merging
- Use pull requests for team development
- Establish branch protection rules when team grows

**For version management**:
- Document clear release process
- Create release checklist
- Consider automation in V2+ if needed

**For long-lived branches**:
- Review open branches weekly
- Delete stale branches
- Encourage frequent integration

## Implementation

### Immediate Actions

1. **Primary branch**: Already renamed to `main`
2. **Create documentation**: `docs/standards/git-branching-strategy.md`
3. **Update all references**: Ensure docs use `main` consistently
4. **Initial tag**: Tag current state as `v0.1.0`

### Branch Protection (Future)

When team grows or project matures, add GitHub branch protection:

```
Settings → Branches → Add rule for main:
- Require pull request reviews (1 approval)
- Require status checks to pass
- Prevent force push
- Prevent deletion
```

For solo development: Self-discipline instead of enforced rules

### Release Process

**Development releases (0.x.y)**:
1. Update `starpunk/__init__.py` version
2. Update `CHANGELOG.md`
3. Commit: `git commit -m "Bump version to 0.x.y"`
4. Tag: `git tag -a v0.x.y -m "Development release 0.x.y"`
5. Push: `git push origin main v0.x.y`

**Stable releases (1.0.0+)**:
1. Update version and changelog
2. Commit version bump
3. Tag: `git tag -a v1.0.0 -m "Release 1.0.0: First stable release"`
4. Push: `git push origin main v1.0.0`

**Hotfixes**:
1. Branch: `git checkout -b hotfix/1.0.1-fix v1.0.0`
2. Fix bug and update version
3. Tag: `git tag -a v1.0.1 -m "Hotfix 1.0.1: Bug fix"`
4. Merge: `git checkout main && git merge hotfix/1.0.1-fix`
5. Push: `git push origin main v1.0.1`
6. Delete: `git branch -d hotfix/1.0.1-fix`

### Documentation

Created comprehensive documentation:
- **Strategy document**: `docs/standards/git-branching-strategy.md`
  - Branch types and naming
  - Workflows and examples
  - Best practices
  - Troubleshooting
- **This ADR**: `docs/decisions/ADR-009-git-branching-strategy.md`
  - Decision rationale
  - Alternatives considered

## Alternatives Considered

### Alternative 1: Git Flow

**Description**: Use full Git Flow with `main`, `develop`, `release`, `hotfix`, `feature` branches

**Pros**:
- Well-established pattern
- Clear separation of development and production
- Structured release process
- Good for scheduled releases

**Cons**:
- Too complex for indie project
- Multiple long-lived branches
- Slower integration
- More overhead
- Designed for different release model

**Rejected**: Complexity doesn't match project scale

### Alternative 2: Trunk-Based Development (Pure)

**Description**: All commits directly to `main`, no feature branches

**Pros**:
- Maximum simplicity
- Fastest integration
- No branch management

**Cons**:
- Risky - broken commits go to main
- No isolation for work in progress
- Difficult for team collaboration
- No experimentation space

**Rejected**: Too risky, doesn't scale to team

### Alternative 3: GitHub Flow (Pure)

**Description**: `main` + feature branches, deploy from `main` continuously

**Pros**:
- Simple and well-documented
- Works well with pull requests
- Fast deployment

**Cons**:
- Designed for continuous deployment
- Doesn't emphasize versioned releases
- No hotfix branch pattern

**Partially adopted**: We use this + semantic versioning + hotfix branches

### Alternative 4: Release Branches Primary

**Description**: Always use release branches, never tag `main` directly

**Pros**:
- Clear release preparation phase
- Can stabilize release while main continues

**Cons**:
- Adds complexity
- Creates long-lived branches
- Overkill for small project

**Rejected**: Unnecessary complexity for V1

### Alternative 5: Keep Master Branch Name

**Description**: Continue using `master` instead of `main`

**Pros**:
- Traditional name
- No migration needed
- No functional difference

**Cons**:
- Outdated convention
- Out of step with industry
- Potentially offensive terminology
- New projects use `main`

**Rejected**: Modern standard is `main`, no reason not to adopt

## References

### Git Branching Models

- [Trunk-Based Development](https://trunkbaseddevelopment.com/) - Pattern we primarily follow
- [GitHub Flow](https://guides.github.com/introduction/flow/) - Simplified flow (close to ours)
- [Git Flow](https://nvie.com/posts/a-successful-git-branching-model/) - More complex model (not adopted)
- [GitLab Flow](https://docs.gitlab.com/ee/topics/gitlab_flow.html) - Hybrid approach

### Branch Naming

- [GitHub Renaming](https://github.com/github/renaming) - Main branch renaming initiative
- [Git Branch Naming](https://deepsource.io/blog/git-branch-naming-conventions/) - Naming conventions

### Versioning Integration

- [Semantic Versioning](https://semver.org/) - Version numbering
- [Git Tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging) - Tag documentation

### Internal Documentation

- [ADR-008: Versioning Strategy](/home/phil/Projects/starpunk/docs/decisions/ADR-008-versioning-strategy.md) - Semantic versioning decision
- [Versioning Strategy](/home/phil/Projects/starpunk/docs/standards/versioning-strategy.md) - Complete versioning spec
- [Git Branching Strategy](/home/phil/Projects/starpunk/docs/standards/git-branching-strategy.md) - Complete branching spec
- [Development Setup](/home/phil/Projects/starpunk/docs/standards/development-setup.md) - Development workflow

---

**ADR**: 009
**Date**: 2025-11-18
**Status**: Accepted
**Decision**: Adopt simplified trunk-based development with `main` branch, feature branches, semantic versioning tags, and hotfix capability
**Supersedes**: None