Branch Management Guidelines

🌿 Branch Strategy Overview

Piper Morgan uses a feature branch workflow with main branch protection for major milestones and infrastructure changes.

📋 Branch Types & Naming

Main Branch (main)

Feature Branches (feature/*)

Development Branches (dev/*)

Release Branches (release/*)

🔄 Branch Lifecycle

1. Creation

# Create feature branch from main
git checkout main
git pull origin main
git checkout -b feature/pm-XXX-description

# Create development branch
git checkout -b dev/component-name

2. Development

3. Completion & Merge

# Option A: Direct merge to main (for major milestones)
git checkout main
git merge feature/branch-name
git push origin main

# Option B: Create pull request (for review)
git push origin feature/branch-name
# Create PR on GitHub, then merge after review

🎯 Merge Decision Matrix

Direct Merge to Main ✅

Pull Request Required 📋

Development Branch Only 🔬

🚀 Current Branch Status (August 19, 2025)

Active Branches

main                              1ec12a1b ✅ Chief Architect Phase 1 Complete
feature/pm-033d-core-coordination ee620e65 [ahead 3] Core coordination work
feature/pm-033d-testing-ui        a2d3f2d9 ✅ PM-033d Phase 4 Complete
test-coverage-augmentation        1ec12a1b ✅ Merged to main

Branch Health

📝 Commit Message Standards

Conventional Commits

feat: add new feature
fix: resolve bug
docs: update documentation
refactor: restructure code
test: add or update tests
chore: maintenance tasks

Examples from This Session

feat: Chief Architect Phase 1 - Smoke Test Infrastructure Complete
docs: add comprehensive testing README and changelog
test: mark 14 database-independent tests with smoke markers

🔧 Branch Maintenance

Weekly Cleanup

# Check for stale branches
git branch --merged main
git branch --no-merged main

# Clean up merged branches
git branch -d feature/completed-feature
git push origin --delete feature/completed-feature

Keeping Branches Current

# Update feature branch with main
git checkout feature/your-branch
git rebase main
# or
git merge main

⚠️ Common Pitfalls & Solutions

Pitfall 1: Working on Wrong Branch

# Check current branch
git branch

# If wrong, stash changes and switch
git stash
git checkout correct-branch
git stash pop

Pitfall 2: Outdated Feature Branch

# Update with main
git checkout feature/your-branch
git rebase main
# Resolve conflicts if any

Pitfall 3: Forgetting to Push

# Check status
git status

# Push if needed
git push origin feature/your-branch

🎯 Immediate Actions Needed

This Week

  1. Review feature/pm-033d-core-coordination - 3 commits ahead, needs attention
  2. Consider merging feature/pm-033d-testing-ui - Phase 4 complete
  3. Clean up test-coverage-augmentation - Now merged to main

Next Session

  1. Establish branch review process for feature merges
  2. Set up branch protection rules on main
  3. Create branch templates for consistent naming

📚 Resources & References

🏁 Quick Reference

Daily Workflow

git checkout main                    # Start from main
git pull origin main                # Get latest
git checkout -b feature/new-work    # Create feature branch
# ... work and commit ...
# (smoke tests run automatically on commit via pre-commit hook)
git checkout main                   # Switch back to main
git merge feature/new-work          # Merge when ready
# (fast tests run automatically on push via pre-push hook)
git push origin main                # Push to remote
git branch -d feature/new-work      # Clean up local

Manual Test Commands

./../../scripts/run_tests.sh smoke     # <5s validation before commits
./../../scripts/run_tests.sh fast      # <30s validation before pushes
./../../scripts/run_tests.sh full      # Complete test suite for releases
./../../scripts/run_tests.sh coverage  # Coverage analysis for quality audits

Emergency Fixes

git checkout main
git checkout -b hotfix/critical-fix
# ... fix and commit ...
git checkout main
git merge hotfix/critical-fix
git push origin main
git branch -d hotfix/critical-fix

Last Updated: August 19, 2025 - Chief Architect Phase 1 Implementation Complete Branch Management Guidelines Established