Git flow

Git Flow Workflow Guide

This guide explains the Git Flow branching model implemented in the Remind Tools project for coordinated development across the Flutter monorepo.

Overview

Git Flow provides a robust framework for managing releases and feature development in our multi-platform Flutter applications. Our implementation coordinates development between two main applications (Trips and Money) and shared packages.

Branch Structure

Core Branches

main - Production Branch

• Purpose: Production-ready code with tagged releases
• Stability: Always deployable to production
• Protection: Fully protected, requires PR approval
• Merges From: release/ and hotfix/ branches only
• Deployments: Automatic to production environments

develop - Integration Branch

• Purpose: Main development integration branch
• Stability: Should always build and pass tests
• Protection: Protected, requires PR reviews
• Merges From: feature/ and bugfix/ branches
• Activity: Daily integration of completed features

Supporting Branches

feature/ - Feature Development

• Naming: feature/[issue-number]-[feature-name]
• Base: Created from develop
• Merge To: develop via Pull Request
• Lifetime: Until feature completion and merge
• Purpose: Individual feature development

release/ - Release Preparation

• Naming: release/[version] (e.g., release/1.2.0)
• Base: Created from develop
• Merge To: Both main and develop
• Purpose: Release stabilization and bug fixes
• Content: Only bug fixes, no new features

hotfix/ - Emergency Fixes

• Naming: hotfix/[version] (e.g., hotfix/1.2.1)
• Base: Created from main
• Merge To: Both main and develop
• Purpose: Critical production bug fixes
• Priority: Immediate deployment required

bugfix/ - Development Bug Fixes

• Naming: bugfix/[issue-number]-[bug-description]
• Base: Created from develop
• Merge To: develop via Pull Request
• Purpose: Non-critical bug fixes during development

Claude Code Integration

Git Flow Commands

The project includes specialized Claude Code commands for Git Flow operations:

/gitflow-start-feature

Initializes new feature development with proper environment setup:

• Creates feature branch from develop
• Runs melos bootstrap
• Validates development environment
• Sets up VS Code workspace

Usage: /gitflow-start-feature payment-integration

/gitflow-finish-feature

Completes feature development with quality validation:

• Runs comprehensive test suite
• Validates code quality and coverage
• Creates pull request to develop
• Handles CI/CD integration

Usage: /gitflow-finish-feature "Add payment processing"

/gitflow-start-release

Begins release preparation with version management:

• Creates release branch from develop
• Coordinates version bumping with Melos
• Prepares platform-specific configurations
• Sets up QA testing environment

Usage: /gitflow-start-release 1.2.0

/gitflow-finish-release

Completes release with production deployment:

• Merges to both main and develop
• Creates version tags
• Coordinates multi-platform deployment
• Updates documentation and changelogs

Usage: /gitflow-finish-release "Release v1.2.0 with new features"

/gitflow-hotfix

Handles emergency production fixes:

• Creates hotfix branch from main
• Implements rapid fix with testing
• Coordinates emergency deployment
• Manages incident communication

Usage: /gitflow-hotfix "Critical payment bug P0"

/gitflow-status

Monitors Git Flow state and branch health:

• Shows current branch status
• Analyzes workflow health
• Identifies merge conflicts
• Reports team activity

Usage: /gitflow-status overview

Development Workflow

Starting New Feature Development

1. Initialize Feature Branch

   /gitflow-start-feature user-authentication
   

   Or manually:

   git checkout develop
   git pull origin develop
   git flow feature start user-authentication
   

2. Development Process

   • Follow Clean Architecture patterns
   • Write comprehensive tests
   • Use conventional commit messages
   • Push regularly for backup

3. Complete Feature

   /gitflow-finish-feature "Add OAuth authentication"
   

Release Management

1. Prepare Release

   /gitflow-start-release 1.3.0
   

2. Stabilization Period

   • Only bug fixes allowed
   • QA testing coordination
   • Platform-specific testing
   • Documentation updates

3. Complete Release

   /gitflow-finish-release "Release v1.3.0"
   

Emergency Hotfixes

1. Emergency Response

   /gitflow-hotfix "Critical database connection issue P0"
   

2. Rapid Development

   • Minimal viable fix
   • Targeted testing
   • Emergency deployment
   • Team communication

Monorepo Considerations

Package Coordination

Cross-Package Changes

• Use workspace scope in commits: feat(workspace):
• Coordinate version bumping with Melos
• Test impact across all applications

App-Specific Changes

• Use app scope: feat(trips): or feat(money):
• Test platform-specific implementations
• Coordinate release timing

Version Management

Semantic Versioning

• MAJOR: Breaking API changes
• MINOR: New features, backward compatible
• PATCH: Bug fixes, backward compatible

Melos Integration

# Coordinate versions across packages
melos version

# Generate changelogs
melos version --changelog

Best Practices

Commit Messages

Feature Branches

✨ feat(trips): add offline map caching
🐛 fix(money): resolve transaction calculation
♻️ refactor(core): improve error handling
✅ test(trips): add integration tests for booking

Release Branches

🐛 fix(release): resolve payment processing edge case
📚 docs(release): update API documentation
🔖 release: prepare v1.2.0 for deployment

Hotfix Branches

🚑 hotfix(critical): fix database connection timeout
🐛 fix(hotfix): resolve authentication bypass vulnerability

Branch Protection Rules

Main Branch

• Require PR reviews (2+ approvals)
• Require status checks (CI/CD)
• Require up-to-date branches
• Restrict push to admins only

Develop Branch

• Require PR reviews (1+ approval)
• Require status checks (tests)
• Allow squash merging
• Delete head branches after merge

CI/CD Integration

Automated Testing

• Unit tests on all branches
• Integration tests on develop/main
• Platform-specific tests on release branches
• Security scans on all PRs

Automated Deployment

• Staging deployment from develop
• Production deployment from main
• Release candidate builds from release branches
• Emergency deployment from hotfix branches

Team Coordination

Daily Workflow

1. Morning Sync

   /gitflow-status health
   

2. Feature Development

   • Start from develop branch
   • Regular commits with conventional format
   • Push to remote frequently

3. End of Day

   • Commit all work in progress
   • Update PR descriptions
   • Review team activity

Weekly Planning

1. Branch Cleanup

   git branch -d $(git branch --merged | grep -v "\*\|main\|develop")
   

2. Release Planning

   • Review features ready for release
   • Plan release timeline
   • Coordinate QA testing

3. Health Assessment

   /gitflow-status overview
   

Troubleshooting

Common Issues

Merge Conflicts

# Update develop and rebase feature
git checkout develop && git pull origin develop
git checkout feature/my-feature
git rebase develop

Failed CI/CD Builds

# Run local validation
melos test
melos run analyze
melos run format

Version Conflicts

# Coordinate with Melos
melos version --dry-run
melos bootstrap

Recovery Procedures

Broken Develop Branch

1. Identify problematic commit
2. Create hotfix if affecting production
3. Revert or fix forward on develop
4. Communicate with team

Emergency Rollback

1. Tag current state for recovery
2. Revert to last known good state
3. Deploy rollback immediately
4. Fix forward in hotfix branch

Monitoring and Metrics

Key Metrics

Development Velocity

• Features completed per sprint
• Average time from feature start to merge
• Code review turnaround time

Quality Metrics

• Test coverage percentage
• Bug escape rate to production
• Hotfix frequency and severity

Process Health

• Branch merge success rate
• CI/CD pipeline success rate
• Time from develop to production

Regular Reviews

Weekly Health Check

• Review branch status and conflicts
• Analyze merge patterns and bottlenecks
• Update process improvements

Monthly Retrospective

• Assess Git Flow effectiveness
• Review tool integration success
• Plan workflow optimizations

This Git Flow implementation ensures coordinated development while maintaining code quality and deployment stability across our Flutter monorepo ecosystem.