Date: 2025-02-27

Status

Accepted

Context

Our growing team and complex development workflow require a standardized approach to branch management that:

• Supports parallel feature development
• Enables safe collaboration across distributed teams
• Maintains clean repository history
• Automates repetitive Git operations
• Integrates with our eXtreme Programming practices (ADR-0015)
• Complements our CI/CD pipeline

Current challenges include:

1. Inconsistent branching strategies between team members
2. Manual merging and pipeline management
3. Difficulty keeping long-lived branches in sync
4. Error-prone release preparation process
5. Lack of standardized workflow for hotfixes

Decision

We will adopt Git Town as our Git workflow automation tool with the following configuration:

1. Branching Model:

   • main as perpetual production-ready branch
   • development as integration branch
   • Feature branches prefixed with feature/
   • Hotfix branches prefixed with hotfix/

2. Workflow Commands:

   • git town hack <feature> - Start new feature
   • git town sync - Sync current branch
   • git town new-pull-request - Create PR
   • git town ship - Ship completed feature

3. Configuration:

   git town main-branch main
   git town perennial-branches development
   git town branch-prefix-delimiter /
   git town sync-strategy rebase
   git town new-branch-push-flag true
   

4. Integration with CI/CD:

   • Branches pushed to origin automatically
   • PR validation via GitHub Actions
   • Ship command triggers deployment

Consequences

Positive

1. Consistent branch management across team
2. Automated sync of feature branches
3. Standardized PR creation
4. Clean, linear commit history
5. Reduced merge conflicts
6. Built-in workflow documentation

Negative

1. Learning curve for Git Town commands
2. Potential conflicts with IDE Git integrations
3. Additional dependency for developers
4. Need to update existing CI/CD scripts

Mitigation Strategies

1. Create Git Town cheatsheet for common workflows

2. Add Git Town configuration to project setup

3. Conduct team training session

4. Update CI/CD to handle Git Town branches

5. Use Git Town aliases in Makefile:

   feature-start:
       git town hack $(name)