Git Branching Strategy - GitFlow Implementation

🎯 ADVANCED WORKFLOW - Use only for projects with scheduled releases. For most tasks, use Git Workflow (GitHub Flow).

Overview

AzmX implements GitFlow for projects requiring structured release management, parallel development, and clear separation between development and production code.

When to use this workflow: - Scheduled releases with specific version numbers (v1.0, v2.0) - Projects with multiple environments (dev, staging, production) - Large features requiring extended development (> 2 weeks) - Critical hotfix requirements for production

For most development tasks: Use GitHub Flow instead - it's simpler and faster for continuous deployment.

When to Use GitFlow vs GitHub Flow

Use GitFlow When:

• Scheduled releases with specific version numbers
• Multiple environments (dev, staging, production)
• Large features requiring extended development
• Hotfix requirements for production
• Semantic versioning is critical

Use GitHub Flow When:

• Continuous deployment to production
• Small to medium features (< 1 week development)
• Simple deployment pipeline
• Rapid iteration preferred

Branch Structure Overview

flowchart TD
    subgraph "GitFlow Branching Strategy"
        subgraph "Development Flow"
            F1[feature/login<br/>📝 Submit code changes<br/>for specific feature] --> D[develop<br/>🔄 Integration branch]
            F2[feature/dashboard<br/>📝 Submit code changes<br/>for specific feature] --> D
            F3[feature/payments<br/>📝 Frequently submit code<br/>for integration testing] --> D
        end

        subgraph "Release Flow"
            D --> R[release/v1.0<br/>🚀 Initiate release branch<br/>for version 1.0]
            R --> M[master/main<br/>✅ Production-ready code]
            R --> D2[develop<br/>🔄 Synchronize corrections<br/>back to develop]
        end

        subgraph "Hotfix Flow"
            M --> H[hotfix/v1.0.1<br/>🚨 Critical production fix]
            H --> M2[master/main<br/>v1.0.1 🏷️]
            H --> D3[develop<br/>🔄 Merge hotfix back]
        end

        subgraph "Tags & Versions"
            M --> T1[Tag v1.0.0<br/>📋 Release version]
            M2 --> T2[Tag v1.0.1<br/>🔧 Hotfix version]
        end
    end

    style F1 fill:#ff6b9d,stroke:#d63384,color:#fff
    style F2 fill:#ff6b9d,stroke:#d63384,color:#fff
    style F3 fill:#ff6b9d,stroke:#d63384,color:#fff
    style D fill:#ffd93d,stroke:#ffcd39,color:#000
    style D2 fill:#ffd93d,stroke:#ffcd39,color:#000
    style D3 fill:#ffd93d,stroke:#ffcd39,color:#000
    style R fill:#6bcf7f,stroke:#51cf66,color:#000
    style H fill:#ff4757,stroke:#ff3838,color:#fff
    style M fill:#3742fa,stroke:#2f3349,color:#fff
    style M2 fill:#3742fa,stroke:#2f3349,color:#fff
    style T1 fill:#e1f5fe,stroke:#0288d1,color:#000
    style T2 fill:#fce4ec,stroke:#c2185b,color:#000

%%{init: {'theme':'base'}}%%
gitGraph
    commit id: "Initial"
    branch develop
    commit id: "Dev setup"

    branch feature-user-auth
    commit id: "Add login"
    commit id: "Add validation"
    checkout develop
    merge feature-user-auth

    branch feature-dashboard
    commit id: "Dashboard UI"
    commit id: "Analytics"
    checkout develop
    merge feature-dashboard

    branch release-v1.0
    commit id: "Release prep"
    commit id: "Version bump"
    commit id: "Bug fixes"

    checkout main
    merge release-v1.0 tag: "v1.0.0"

    checkout develop
    merge release-v1.0

    checkout main
    branch hotfix-critical-fix
    commit id: "Critical fix"

    checkout main
    merge hotfix-critical-fix tag: "v1.0.1"

    checkout develop
    merge hotfix-critical-fix

Branch Types

Main Branches

main/master - Production-ready code only - Permanent lifetime - Highly protected, no direct commits - Auto-deploy to production

develop - Integration branch for next release - Permanent lifetime - Features merge here before release - Auto-deploy to development environment

Supporting Branches

Feature Branches

• Branch from: develop
• Merge to: develop
• Naming: feature/CU-123-description
• Lifetime: Delete after merge

Creating Feature Branches:

You have two options for creating feature branches:

Option A: ClickUp Branch Button (Recommended) ⭐

1. Open your task in ClickUp
2. Click the "Create Branch" button in the task details
3. ClickUp automatically generates branch name: feature/CU-{id}-{description}
4. Copy the branch name
5. In your terminal:

   git fetch
   git checkout feature/CU-abc123-your-feature
   

Benefits: - Automatic correct formatting with task ID - Task is automatically linked to branch - No manual branch name construction

Option B: Manual Branch Creation

1. Note your task ID from ClickUp (e.g., CU-86evg8jk0)
2. Create branch locally:

   git checkout develop
   git pull origin develop
   git checkout -b feature/CU-86evg8jk0-user-dashboard
   

Complete Feature Branch Workflow:

# Option A: From ClickUp button
git fetch
git checkout feature/CU-abc123-user-dashboard

# Option B: Manual creation
git checkout develop
git pull origin develop
git checkout -b feature/CU-abc123-user-dashboard

# Work on feature
git add .
git commit -m "feat(dashboard): add user analytics component"
git push -u origin feature/CU-abc123-user-dashboard

# Create PR through GitHub
# After PR merged, cleanup
git checkout develop
git pull origin develop
git branch -d feature/CU-abc123-user-dashboard

Release Branches

• Branch from: develop
• Merge to: main AND develop
• Naming: release/v* (e.g., release/v1.2.0)
• Purpose: Version bumps, bug fixes, final testing (no new features)

# Create release branch
git checkout develop
git pull origin develop
git checkout -b release/v1.2.0

# Release preparation: version bumps, bug fixes, docs
npm version 1.2.0 --no-git-tag-version

# Finalize release
git checkout main
git merge release/v1.2.0
git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin main v1.2.0

# Merge back to develop
git checkout develop
git merge release/v1.2.0
git push origin develop

# Cleanup
git branch -d release/v1.2.0
git push origin --delete release/v1.2.0

Hotfix Branches

• Branch from: main
• Merge to: main AND develop
• Naming: hotfix/v* (e.g., hotfix/v1.2.1)
• Purpose: Critical production fixes only

# Create hotfix branch
git checkout main
git pull origin main
git checkout -b hotfix/v1.2.1

# Apply critical fix
git add .
git commit -m "hotfix(auth): fix critical security vulnerability"

# Merge to main
git checkout main
git merge hotfix/v1.2.1
git tag -a v1.2.1 -m "Hotfix version 1.2.1"
git push origin main v1.2.1

# Merge to develop
git checkout develop
git merge hotfix/v1.2.1
git push origin develop

# Cleanup
git branch -d hotfix/v1.2.1

Semantic Versioning

Version Format: MAJOR.MINOR.PATCH

MAJOR (X.0.0) - Breaking changes - API changes breaking backward compatibility - Database schema breaking changes - Framework major version upgrades

MINOR (0.X.0) - New features (backward compatible) - New functionality or enhancements - New API endpoints - Performance improvements

PATCH (0.0.X) - Bug fixes - Bug fixes without new functionality - Security patches - Performance optimizations

Pre-release versions:

v1.2.0-alpha.1    # Alpha release
v1.2.0-beta.1     # Beta release
v1.2.0-rc.1       # Release candidate

Workflow Guidelines

Key Workflow Patterns

Role-Specific Responsibilities

Developers: - Create feature branches from develop - Follow naming conventions - Write meaningful commit messages - Ensure tests pass before PR - Keep branches focused and small

Tech Leads: - Review and approve release branches - Manage hotfix process - Approve breaking changes - Oversee version numbering

Branch Protection Rules

main Branch Protection

protection_rules:
  main:
    required_reviews: 2
    dismiss_stale_reviews: true
    require_code_owner_reviews: true
    required_status_checks:
      - continuous-integration
      - sonarqube-quality-gate
      - security-scan
    enforce_admins: true

develop Branch Protection

protection_rules:
  develop:
    required_reviews: 1
    required_status_checks:
      - continuous-integration
      - unit-tests
    allow_force_pushes: false

Common Scenarios

Merge Conflicts

# When merging release to main encounters conflicts
git checkout main
git merge release/v1.3.0
# CONFLICT: Merge conflict in file.js

# Resolution:
# 1. Edit conflicted files and remove conflict markers
# 2. Test the resolution
git add .
git commit -m "resolve merge conflicts in release v1.3.0"

Emergency Hotfix During Active Release

# 1. Complete current release first
git checkout main
git merge release/v1.3.0
git tag v1.3.0

# 2. Create and apply hotfix immediately
git checkout -b hotfix/v1.3.1
# Apply fix, then merge
git checkout main
git merge hotfix/v1.3.1
git tag v1.3.1

# 3. Merge hotfix to develop
git checkout develop
git merge hotfix/v1.3.1

ClickUp Integration

Branch Naming with ClickUp Tasks

All feature, fix, and hotfix branches should include ClickUp task IDs for automatic PR linking:

# Feature branches with ClickUp IDs
feature/CU-abc123-user-authentication
feature/CU-def456-payment-gateway-integration
feature/CU-ghi789-analytics-dashboard

# Fix branches with ClickUp IDs
fix/CU-jkl012-login-validation-bug
fix/CU-mno345-payment-timeout-issue

# Hotfix branches with ClickUp IDs
hotfix/CU-pqr678-critical-security-patch
hotfix/CU-stu901-production-data-fix

# Release branches (no task ID needed)
release/v2.1.0
release/v2.2.0

Benefits of ClickUp Integration: - PRs automatically link to ClickUp tasks - Task status updates on PR merge - Streamlined project tracking - Automated workflow visibility

See GitHub-ClickUp Quick Start and GitHub-ClickUp Workflow for complete setup and usage guide.

References

GitFlow & Versioning: - A Successful Git Branching Model - Original GitFlow paper - Semantic Versioning Specification - GitHub Flow vs GitFlow Comparison

AzmX Internal: - Git Workflow - GitHub Flow - Alternative simplified approach - Git Branch Naming Conventions - Detailed naming rules and ClickUp format - GitHub-ClickUp Integration Workflow - Daily usage patterns