# Git Branching Strategy for Infrastructure Management

## Branch Structure

### Main Branches

#### `main`
- **Purpose**: Production-ready configurations
- **Protection**: Protected branch with required reviews
- **Deployment**: Automatically deployed to production machines
- **Stability**: Should always be stable and tested

#### `develop`
- **Purpose**: Integration branch for new features
- **Testing**: Continuous integration testing
- **Merging**: Features merge here first
- **Deployment**: Deployed to staging/test environments

### Supporting Branches

#### Feature Branches: `feature/<description>`
- **Purpose**: Development of new features or modules
- **Naming**: `feature/add-cosmic-desktop`, `feature/sleeper-service-config`
- **Lifetime**: Temporary, deleted after merge
- **Source**: Branch from `develop`
- **Merge**: Merge back to `develop`

#### Machine Branches: `machine/<machine-name>`
- **Purpose**: Machine-specific configuration changes
- **Naming**: `machine/congenital-optimist`, `machine/sleeper-service`
- **Use Case**: Testing machine-specific changes
- **Merge**: Merge to `develop` after testing

#### Hotfix Branches: `hotfix/<issue>`
- **Purpose**: Critical fixes for production
- **Naming**: `hotfix/security-patch`, `hotfix/boot-failure`
- **Source**: Branch from `main`
- **Merge**: Merge to both `main` and `develop`

#### Module Branches: `module/<module-name>`
- **Purpose**: Development of specific modules
- **Naming**: `module/virtualization`, `module/desktop-gnome`
- **Scope**: Single module focus
- **Testing**: Module-specific testing

### Tagging Strategy

#### Version Tags: `v<major>.<minor>.<patch>`
- **Purpose**: Mark stable releases
- **Format**: `v1.0.0`, `v1.2.1`
- **Trigger**: Major configuration milestones
- **Deployment**: Tag triggers deployment workflows

#### Machine Tags: `<machine>-v<version>`
- **Purpose**: Machine-specific deployments
- **Format**: `congenital-optimist-v1.0.0`
- **Use Case**: Track per-machine configurations
- **Rollback**: Enable machine-specific rollbacks

#### Phase Tags: `phase-<number>-complete`
- **Purpose**: Mark migration phase completion
- **Format**: `phase-1-complete`, `phase-2-complete`
- **Documentation**: Link to plan.md milestones

## Workflow Examples

### Standard Feature Development
```bash
# Start new feature
git checkout develop
git pull origin develop
git checkout -b feature/add-incus-clustering

# Develop and test
# ... make changes ...
nix flake check
sudo nixos-rebuild test --flake .#congenital-optimist

# Commit and push
git add .
git commit -m "feat: add Incus clustering support"
git push origin feature/add-incus-clustering

# Create PR to develop
# ... review process ...
# Merge to develop
```

### Machine-Specific Changes
```bash
# Machine-specific branch
git checkout develop
git checkout -b machine/sleeper-service

# Test on specific machine
sudo nixos-rebuild test --flake .#sleeper-service

# Commit and merge
git add .
git commit -m "feat(sleeper-service): add NFS server configuration"
```

### Hotfix Process
```bash
# Critical fix needed
git checkout main
git checkout -b hotfix/zfs-boot-failure

# Fix the issue
# ... emergency fix ...
sudo nixos-rebuild test --flake .#congenital-optimist

# Deploy to main
git add .
git commit -m "fix: resolve ZFS boot failure"
git checkout main
git merge hotfix/zfs-boot-failure
git tag v1.0.1

# Backport to develop
git checkout develop
git merge hotfix/zfs-boot-failure
```

## Commit Convention

### Format
```
<type>(<scope>): <description>

[optional body]

[optional footer]
```

### Types
- **feat**: New feature or module
- **fix**: Bug fix
- **docs**: Documentation changes
- **style**: Formatting, missing semicolons, etc.
- **refactor**: Code refactoring
- **test**: Adding tests
- **chore**: Maintenance tasks

### Scopes
- **machine**: `(congenital-optimist)`, `(sleeper-service)`
- **module**: `(desktop)`, `(virtualization)`, `(users)`
- **config**: `(flake)`, `(ci)`
- **docs**: `(readme)`, `(plan)`

### Examples
```bash
feat(desktop): add Cosmic desktop environment module
fix(virtualization): resolve Incus networking issues
docs(readme): update installation instructions
refactor(modules): reorganize desktop environment modules
chore(ci): update GitHub Actions workflow
```

## Branch Protection Rules

### Main Branch Protection
- **Required Reviews**: 1 reviewer minimum
- **Status Checks**: All CI checks must pass
- **Up-to-date**: Branch must be up to date before merging
- **Admin Override**: Allow admin override for hotfixes
- **Force Push**: Disabled
- **Deletion**: Disabled

### Develop Branch Protection
- **Required Reviews**: 1 reviewer (can be self-review)
- **Status Checks**: All CI checks must pass
- **Auto-merge**: Allow auto-merge after checks
- **Force Push**: Disabled for others

## Merge Strategies

### Feature to Develop
- **Strategy**: Squash and merge
- **Reason**: Clean history, single commit per feature
- **Title**: Use conventional commit format

### Develop to Main
- **Strategy**: Merge commit
- **Reason**: Preserve feature branch history
- **Testing**: Full integration testing required

### Hotfix to Main
- **Strategy**: Fast-forward if possible
- **Reason**: Immediate deployment needed
- **Testing**: Minimal but critical testing

## Deployment Strategy

### Automatic Deployment
- **main** → Production machines (congenital-optimist, sleeper-service)
- **develop** → Test environment (if available)

### Manual Deployment
- Feature branches can be manually deployed for testing
- Use `nixos-rebuild test` for non-persistent testing
- Use `nixos-rebuild switch` for persistent changes

### Rollback Strategy
```bash
# Rollback to previous version
git checkout main
git revert <commit-hash>
git tag rollback-v1.0.0-to-v0.9.9

# Or rollback to specific tag
git checkout v1.0.0
sudo nixos-rebuild switch --flake .#congenital-optimist
```

## Branch Lifecycle

### Weekly Maintenance
- **Monday**: Review open feature branches
- **Wednesday**: Merge develop to main if stable
- **Friday**: Clean up merged feature branches
- **Sunday**: Update dependencies (automated)

### Monthly Tasks
- Review and update branch protection rules
- Clean up old tags and releases
- Update documentation
- Security audit of configurations

## Best Practices

### Branch Naming
- Use descriptive names: `feature/improve-zfs-performance`
- Include issue numbers: `feature/123-add-cosmic-desktop`
- Use lowercase with hyphens
- Keep names under 50 characters

### Commit Messages
- Use imperative mood: "add", "fix", "update"
- Keep first line under 50 characters
- Include body for complex changes
- Reference issues: "Fixes #123"

### Testing Requirements
- Always run `nix flake check` before committing
- Test with `nixos-rebuild test` on relevant machines
- Document testing performed in PR description
- Consider impact on other machines

### Code Review
- Focus on configuration correctness
- Check for security implications
- Verify documentation updates
- Ensure rollback plan exists
- Test locally when possible

---

This branching strategy ensures stable, tested configurations while enabling rapid development and emergency fixes when needed.