> ## Documentation Index
> Fetch the complete documentation index at: https://docs.remind.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# 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**
   ```bash theme={null}
   /gitflow-start-feature user-authentication
   ```
   Or manually:
   ```bash theme={null}
   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**
   ```bash theme={null}
   /gitflow-finish-feature "Add OAuth authentication"
   ```

### Release Management

1. **Prepare Release**
   ```bash theme={null}
   /gitflow-start-release 1.3.0
   ```

2. **Stabilization Period**
   * Only bug fixes allowed
   * QA testing coordination
   * Platform-specific testing
   * Documentation updates

3. **Complete Release**
   ```bash theme={null}
   /gitflow-finish-release "Release v1.3.0"
   ```

### Emergency Hotfixes

1. **Emergency Response**
   ```bash theme={null}
   /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**

```bash theme={null}
# Coordinate versions across packages
melos version

# Generate changelogs
melos version --changelog
```

## Best Practices

### Commit Messages

**Feature Branches**

```bash theme={null}
✨ 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**

```bash theme={null}
🐛 fix(release): resolve payment processing edge case
📚 docs(release): update API documentation
🔖 release: prepare v1.2.0 for deployment
```

**Hotfix Branches**

```bash theme={null}
🚑 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**
   ```bash theme={null}
   /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**
   ```bash theme={null}
   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**
   ```bash theme={null}
   /gitflow-status overview
   ```

## Troubleshooting

### Common Issues

**Merge Conflicts**

```bash theme={null}
# Update develop and rebase feature
git checkout develop && git pull origin develop
git checkout feature/my-feature
git rebase develop
```

**Failed CI/CD Builds**

```bash theme={null}
# Run local validation
melos test
melos run analyze
melos run format
```

**Version Conflicts**

```bash theme={null}
# 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.