05_17_01: Branching Model - AudioLab Git Workflow¶
Executive Summary¶
The AudioLab Branching Model implements a hybrid GitFlow strategy optimized for audio plugin development. It combines the stability of GitFlow with flexibility for platform-specific development and long-running DSP experiments.
Key Features: - Hybrid GitFlow + Custom Strategy - Platform-specific branches (macOS, Windows, Linux) - Experimental research branches - Automated branch protection and enforcement - Comprehensive merge strategies - Quality gates at every merge point
Philosophy¶
Audio development requires a branching strategy that balances:
- Stability: Production releases must be rock-solid
- Flexibility: DSP research needs room to experiment
- Platform Support: Different platforms require parallel development
- Rapid Iteration: Quick bug fixes without blocking development
- Collaboration: Clear workflows for distributed teams
Branch Structure¶
Permanent Branches¶
main¶
- Purpose: Production-ready stable code
- Protection: Maximum (locked)
- Deployable: Always
- Merge Sources:
release/*,hotfix/*only - Requirements: All tests pass, 2 approvals, full documentation
develop¶
- Purpose: Integration branch for next release
- Protection: High
- Deployable: No
- Merge Sources:
feature/*,bugfix/*,refactor/*,platform/* - Requirements: Core tests pass, 1 approval
Temporary Branches¶
Feature Branches: feature/*¶
# Pattern
feature/[issue-id]-[short-description]
# Examples
feature/AL-123-reverb-engine
feature/AL-456-midi-learn
feature/spectral-gate
- Base:
develop - Target:
develop - Lifetime: 1-4 weeks (max 8 weeks)
- Strategy: Squash merge
- Requirements: Tests pass, documentation updated
Bug Fix Branches: bugfix/*¶
# Pattern
bugfix/[issue-id]-[bug-description]
# Examples
bugfix/AL-789-audio-glitch
bugfix/AL-234-preset-load-crash
- Base:
develop - Target:
develop - Lifetime: 1-3 days (max 2 weeks)
- Strategy: Squash merge
- Requirements: Regression test included
Hotfix Branches: hotfix/*¶
# Pattern
hotfix/[version]-[critical-issue]
# Examples
hotfix/2.1.4-security-patch
hotfix/2.1.4-crash-on-load
- Base:
main - Target:
main+develop - Lifetime: Hours to 1 day
- Priority: Critical
- Strategy: Merge commit
- Requirements: Emergency approval, immediate testing
Release Branches: release/*¶
- Base:
develop - Target:
main+develop - Lifetime: 2-8 weeks (alpha → beta → rc → stable)
- Allowed Changes: Bug fixes, version bumps, documentation
- Not Allowed: New features, refactoring, breaking changes
Platform-Specific Branches¶
macOS: platform/macos/*¶
Windows: platform/windows/*¶
Linux: platform/linux/*¶
- Base:
develop - Lifetime: 1-3 months (max 6 months)
- Requirements: Platform-specific tests pass, no regressions
Experimental Branches¶
Pattern: experiment/*¶
# Pattern
experiment/[researcher-name]/[experiment-name]
# Examples
experiment/dsp-team/neural-reverb
experiment/audio-research/ml-denoiser
experiment/perf/simd-optimization
- Base:
develop - Lifetime: 1-6 months (max 12 months)
- Stability: Experimental - no guarantees
- Merge Policy: Must graduate to
feature/*first - Requirements: Proof of concept, performance validation, team review
Vendor Integration Branches¶
Pattern: vendor/*¶
- Purpose: Integration with external SDKs
- Lifetime: Permanent
- Sync: On vendor releases
Branch Protection Rules¶
Maximum Protection (main)¶
- ❌ No direct commits
- ❌ No force push
- ❌ No deletion
- ✅ Require pull request
- ✅ Require 2 approvals
- ✅ Require signed commits
- ✅ Require linear history
- ✅ Lock branch
- ✅ All CI checks must pass
High Protection (develop)¶
- ❌ No direct commits
- ❌ No force push
- ✅ Require pull request
- ✅ Require 1 approval
- ✅ Require signed commits
- ✅ Core CI checks must pass
Low Protection (feature/, bugfix/)¶
- ✅ Direct commits allowed
- ✅ Force push allowed (for rebase)
- ✅ Can be deleted
- ⚪ Pull request optional
Merge Strategies¶
Squash Merge¶
Used for: feature/* → develop, release/* → main
Advantages: - Clean linear history - One feature = one commit - Easy to revert
Example:
git checkout develop
git merge --squash feature/AL-123-reverb-engine
git commit -m "feat(dsp): add reverb engine (AL-123)"
Merge Commit¶
Used for: develop → main, hotfix/* → main
Advantages: - Preserves complete history - Shows branch relationships - Maintains audit trail
Example:
Rebase¶
Used for: Internal feature development
Advantages: - Linear history - Preserves individual commits - Clean timeline
Example:
Workflow Examples¶
Creating a Feature¶
# 1. Create feature branch from develop
python branch_manager.py create feature AL-123-reverb-engine
# 2. Develop feature
git add .
git commit -m "feat(dsp): implement reverb core"
# 3. Keep synchronized with develop
git fetch origin develop
git rebase origin/develop
# 4. Push to remote
git push -u origin feature/AL-123-reverb-engine
# 5. Create pull request
# (Use GitHub/GitLab UI)
# 6. Merge using branch_manager
python branch_manager.py merge feature/AL-123-reverb-engine develop --strategy squash
# 7. Delete feature branch
git branch -d feature/AL-123-reverb-engine
Creating a Release¶
# 1. Create release branch from develop
git checkout -b release/2.1 develop
# 2. Bump version
python version_manager.py bump minor
python version_manager.py phase alpha 1
# 3. Test and fix bugs (no new features!)
git commit -m "fix(ui): resolve layout issue"
# 4. Progress through phases
python version_manager.py phase beta 1 # Testing
python version_manager.py phase rc 1 # Release candidate
python version_manager.py phase stable # Production
# 5. Merge to main
git checkout main
git merge --no-ff release/2.1
git tag v2.1.0
# 6. Merge back to develop
git checkout develop
git merge --no-ff release/2.1
# 7. Delete release branch
git branch -d release/2.1
Emergency Hotfix¶
# 1. Create hotfix from main
git checkout -b hotfix/2.1.1-security-patch main
# 2. Fix critical issue
git commit -m "fix(security): patch vulnerability CVE-2024-XXXX"
# 3. Test hotfix
# (Run regression tests)
# 4. Merge to main
git checkout main
git merge --no-ff hotfix/2.1.1-security-patch
git tag v2.1.1
# 5. Merge to develop
git checkout develop
git merge --no-ff hotfix/2.1.1-security-patch
# 6. Deploy immediately
# (Trigger CI/CD)
# 7. Cleanup
git branch -d hotfix/2.1.1-security-patch
Branch Manager CLI¶
Installation¶
Commands¶
Create Branch¶
# Create feature branch
python branch_manager.py create feature AL-123-reverb-engine
# Create bugfix branch
python branch_manager.py create bugfix AL-456-audio-dropout
# Create platform branch
python branch_manager.py create platform linux/jack-support
Validate Branch Name¶
python branch_manager.py validate feature/AL-123-reverb-engine
# ✅ Valid branch name
python branch_manager.py validate temp-branch
# ❌ Branch name contains forbidden word: ['temp']
List Branches¶
# List all branches
python branch_manager.py list
# List by type
python branch_manager.py list --type feature
Merge Branch¶
# Squash merge (default)
python branch_manager.py merge feature/AL-123 develop --strategy squash
# Merge commit
python branch_manager.py merge hotfix/2.1.1 main --strategy merge_commit
# Rebase
python branch_manager.py merge feature/AL-123 develop --strategy rebase
Branch Status¶
Output:
============================================================
AudioLab Branch Status
============================================================
Current branch: develop
Total branches: 23
Branches by type:
feature : 8
bugfix : 3
platform : 2
experiment : 1
hotfix : 0
⚠️ Stale branches (3):
feature/old-experiment (87 days old)
platform/windows/old-driver (62 days old)
bugfix/minor-fix (45 days old)
============================================================
Cleanup Merged Branches¶
# Dry run (preview)
python branch_manager.py cleanup --dry-run
# Actually delete
python branch_manager.py cleanup
Delete Branch¶
# Regular delete (safe)
python branch_manager.py delete feature/AL-123-reverb-engine
# Force delete (unmerged)
python branch_manager.py delete feature/abandoned-work --force
Quality Gates¶
Feature → Develop¶
- ✅ Unit tests pass
- ✅ Integration tests pass
- ✅ Code review approved
- ✅ Documentation updated
- ✅ No breaking changes (or documented)
Release → Main¶
- ✅ All platforms build
- ✅ All tests pass (100%)
- ✅ Code coverage ≥ 90%
- ✅ Security scan clean
- ✅ Performance benchmarks met
- ✅ 2 approvals obtained
- ✅ Release notes complete
- ✅ Documentation finalized
Hotfix → Main¶
- ✅ Regression test passes
- ✅ Emergency approval obtained
- ✅ Risk assessment completed
- ✅ No new bugs introduced
Automation¶
Branch Lifecycle¶
Stale Detection: - Feature branches: Warning after 6 weeks, auto-close after 8 weeks - Bugfix branches: Warning after 2 weeks - Experimental: Warning after 8 weeks
Auto-Cleanup: - Merged branches deleted immediately (except platform/vendor) - Unmerged stale branches auto-closed after 12 weeks
Merge Automation¶
Pre-Merge Hooks: 1. Validate commit messages 2. Check code ownership 3. Verify changelog entry 4. Run linting
Post-Merge Hooks: 1. Update version file 2. Generate changelog 3. Notify team 4. Clean up branches 5. Trigger CI/CD
Naming Conventions¶
Format¶
Rules¶
- ✅ Use lowercase
- ✅ Use hyphens for spaces
- ✅ Keep descriptions short (<50 chars)
- ✅ Use meaningful names
- ✅ Include issue ID when applicable
Forbidden Names¶
- ❌ temp, test, wip, backup, old
Good Examples¶
- ✅
feature/AL-123-reverb-engine - ✅
bugfix/AL-456-audio-dropout - ✅
hotfix/2.1.4-security-patch - ✅
platform/macos/m1-optimization - ✅
experiment/dsp-team/neural-reverb
Bad Examples¶
- ❌
temp-branch - ❌
johns-stuff - ❌
test123 - ❌
fix
Conflict Resolution¶
Prevention¶
- Regular syncs: Keep feature branches synchronized with develop
- Small changes: Small, focused commits reduce conflicts
- Communication: Coordinate with team on shared code
- Code ownership: Respect CODEOWNERS boundaries
Resolution Strategies¶
Manual Resolution (required for): - Architecture changes - API modifications - Complex logic conflicts
Automatic Resolution (allowed for): - Documentation files - Configuration files (non-critical) - Test data
Resolution Rules:
- Prefer target: package.json, CMakeLists.txt, .gitignore
- Prefer source: src/**/*.cpp, src/**/*.h, tests/**/*
- Manual review: include/**/*.h, public-api/**/*
Metrics and Monitoring¶
Tracked Metrics¶
- Branch lifetime
- Merge frequency
- Conflict rate
- Time to merge
- Failed merges
- Stale branches
Targets¶
- Feature lifetime: <4 weeks
- Time to merge: <3 days after PR
- Conflict rate: <10%
- Stale branches: <5
Reports¶
- Weekly: Branch protection compliance, failed merge analysis
- Monthly: Security posture, review efficiency, branch health
Best Practices¶
DO ✅¶
- Create descriptive branch names
- Keep branches short-lived
- Sync frequently with base branch
- Write clear commit messages
- Review code thoroughly
- Run tests before merging
- Delete merged branches
DON'T ❌¶
- Commit directly to main/develop
- Create long-lived feature branches
- Use generic branch names
- Skip code review
- Merge with failing tests
- Force push to protected branches
- Ignore merge conflicts
Integration with Version Control System¶
GitFlow Compliance¶
- ✅ Feature branches from develop
- ✅ Hotfix branches from main
- ✅ Release branches from develop
- ✅ All merges follow defined strategies
Custom Extensions¶
- ✅ Platform branches for parallel development
- ✅ Experimental branches for research
- ✅ Vendor branches for SDK integration
Troubleshooting¶
Branch Won't Merge¶
- Check for merge conflicts:
python branch_manager.py merge source target - Sync with target:
git fetch origin && git rebase origin/target - Resolve conflicts manually
- Re-run tests
- Try merge again
Branch Protection Violation¶
- Check protection rules: See
branch_protection.yaml - Ensure all checks pass
- Obtain required approvals
- Contact admin for emergency override (if critical)
Stale Branch Warning¶
- Evaluate if work is still needed
- If yes: Update branch and continue
- If no: Close PR and delete branch
- If blocked: Document reason and request extension
Configuration Files¶
- branching_model.yaml: Complete branching strategy configuration
- branch_protection.yaml: Protection rules and enforcement
- merge_strategies.yaml: Merge strategies and quality gates
- branch_manager.py: CLI tool for branch management
References¶
Next Steps¶
After implementing the branching model:
- Configure CI/CD: Set up automated checks for each branch type
- Set up Git hooks: Install pre-commit, pre-push hooks
- Train team: Conduct branching model workshop
- Create CODEOWNERS: Define code ownership boundaries
- Implement commit conventions: Set up commitlint (TAREA 3)
Part of AudioLab Version Control System (05_17_VERSION_CONTROL)