Developer Guide
Git Branching Strategy

MTD Git Branching Strategy

This document outlines the git branching strategy for the Manage The Day (MTD) multi-project repository, covering all three projects: mtd-ai, mtd-web-v2, and mtd-docs.

Overview

The MTD project uses a Git Flow-inspired branching model with dev as the default branch and main as the production deployment trigger. This strategy ensures stable releases while enabling continuous development across multiple teams and projects.

Branch Types and Hierarchy

Core Branches

main - Production Branch

  • Purpose: Contains production-ready code
  • Protection: Highly protected, requires pull requests
  • Deployment: Automatically triggers production deployment
  • Merges From: release/* and hotfix/* branches only
  • Direct Commits: Prohibited

dev - Default Development Branch

  • Purpose: Integration branch for ongoing development
  • Default: Set as the default branch for new clones
  • Merges From: feature/*, bugfix/*, release/*, and hotfix/* branches
  • Testing: All CI/CD checks must pass before merging
  • Direct Commits: Limited to minor configuration changes

Supporting Branches

feature/* - Feature Development

  • Naming: feature/description (e.g., feature/user-authentication)
  • Branch From: dev
  • Merge To: dev via Pull Request
  • Lifespan: Short-lived (days to weeks)
  • Purpose: Develop new features and enhancements

bugfix/* - Bug Fixes

  • Naming: bugfix/description (e.g., bugfix/login-validation-error)
  • Branch From: dev
  • Merge To: dev via Pull Request
  • Lifespan: Short-lived (hours to days)
  • Purpose: Fix non-critical bugs identified in development

release/* - Release Preparation

  • Naming: release/version (e.g., release/v2.1.0)
  • Branch From: dev
  • Merge To: Both main and dev
  • Lifespan: Medium-lived (days to weeks)
  • Purpose: Prepare releases, final testing, version bumps

hotfix/* - Critical Production Fixes

  • Naming: hotfix/description (e.g., hotfix/critical-auth-vulnerability)
  • Branch From: main
  • Merge To: Both main and dev
  • Lifespan: Short-lived (hours to days)
  • Purpose: Fix critical production issues immediately

Development Workflow

1. Feature Development

# Start new feature
git checkout dev
git pull origin dev
git checkout -b feature/new-user-dashboard
 
# Develop feature
# ... make changes, commit regularly ...
git add .
git commit -m "feat: add user dashboard components"
 
# Push and create PR
git push origin feature/new-user-dashboard
# Create Pull Request to dev branch

2. Bug Fixes

# Start bug fix
git checkout dev
git pull origin dev
git checkout -b bugfix/fix-timer-calculation
 
# Fix bug
# ... make changes ...
git add .
git commit -m "fix: correct timer calculation logic"
 
# Push and create PR
git push origin bugfix/fix-timer-calculation
# Create Pull Request to dev branch

3. Release Process

# Create release branch
git checkout dev
git pull origin dev
git checkout -b release/v2.1.0
 
# Prepare release (version bumps, final testing, documentation)
git add .
git commit -m "chore: bump version to 2.1.0"
 
# Create PRs to both main and dev
git push origin release/v2.1.0
# Create PR to main (triggers production deployment)
# Create PR to dev (incorporates any release changes)
 
# Tag the release after merge to main
git checkout main
git pull origin main
git tag -a v2.1.0 -m "Release version 2.1.0"
git push origin v2.1.0

4. Hotfix Process

# Create hotfix from main
git checkout main
git pull origin main
git checkout -b hotfix/fix-critical-auth-bug
 
# Fix critical issue
git add .
git commit -m "hotfix: resolve authentication bypass vulnerability"
 
# Create PRs to both main and dev
git push origin hotfix/fix-critical-auth-bug
# Create PR to main (immediate production fix)
# Create PR to dev (incorporate fix into development)
 
# Tag hotfix after merge
git checkout main
git pull origin main
git tag -a v2.0.1 -m "Hotfix version 2.0.1"
git push origin v2.0.1

Multi-Project Considerations

The MTD repository contains three projects that share the same branching strategy:

Project Structure

mtd/
├── mtd-ai/           # Python FastAPI backend
├── mtd-web-v2/       # Next.js React frontend  
├── mtd-docs/         # Nextra documentation
└── GIT_BRANCHING_STRATEGY.md

Cross-Project Development

Feature Branches Spanning Multiple Projects

When a feature requires changes across multiple projects:

# Single branch for multi-project features
git checkout -b feature/ai-agent-integration
 
# Make changes in multiple projects
# mtd-ai/: Add new agent endpoints
# mtd-web-v2/: Add agent UI components
# mtd-docs/: Update agent documentation
 
# Commit changes logically by project
git add mtd-ai/
git commit -m "feat(backend): add AI agent management endpoints"
 
git add mtd-web-v2/
git commit -m "feat(frontend): add agent creation UI components"
 
git add mtd-docs/
git commit -m "docs: add AI agent user guide"

Project-Specific Changes

For changes affecting only one project, include project prefix in branch name:

# Backend-only changes
git checkout -b feature/mtd-ai/vertex-ai-integration
 
# Frontend-only changes  
git checkout -b feature/mtd-web-v2/mobile-responsive-design
 
# Documentation-only changes
git checkout -b feature/mtd-docs/api-reference-update

Pull Request Guidelines

Branch Protection Rules

main Branch

  • Require pull request reviews (2 reviewers minimum)
  • Require status checks to pass
  • Require branches to be up to date
  • Restrict pushes to administrators only
  • Include administrators in restrictions

dev Branch

  • Require pull request reviews (1 reviewer minimum)
  • Require status checks to pass
  • Require branches to be up to date
  • Allow administrators to bypass

PR Requirements

All Pull Requests Must Include:

  1. Clear Description: What changes are made and why
  2. Testing Evidence: Screenshots, test results, or testing steps
  3. Breaking Changes: Document any breaking changes
  4. Documentation Updates: Update relevant documentation
  5. Linked Issues: Reference related GitHub issues

Project-Specific Requirements:

mtd-ai (Backend):

  • Run python run_tests.py
  • Include API documentation updates
  • Verify authentication flows
  • Test with development Firebase project

mtd-web-v2 (Frontend):

  • Run npm run type-check (critical requirement)
  • Include UI/UX screenshots for visual changes
  • Test across different screen sizes
  • Verify user plan detection logic

mtd-docs (Documentation):

  • Run pnpm build to verify build success
  • Preview documentation changes locally
  • Ensure proper navigation structure

Commit Message Conventions

Follow Conventional Commits (opens in a new tab) specification:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code
  • refactor: A code change that neither fixes a bug nor adds a feature
  • test: Adding missing tests or correcting existing tests
  • chore: Changes to the build process or auxiliary tools

Examples:

git commit -m "feat(auth): implement OAuth2 login flow"
git commit -m "fix(timer): resolve negative time calculation bug"
git commit -m "docs(api): update agent endpoint documentation"
git commit -m "chore(deps): update Next.js to v13.5.0"

Deployment Strategy

Automatic Deployments

Production (main branch)

  • Trigger: Merge to main branch
  • Projects:
    • mtd-ai: Deploy to Google Cloud Run (production)
    • mtd-web-v2: Deploy to Firebase Hosting (production)
    • mtd-docs: Deploy to Firebase Hosting (production)

Development (dev branch)

  • Trigger: Merge to dev branch
  • Projects:
    • mtd-ai: Deploy to development environment
    • mtd-web-v2: Deploy to staging environment
    • mtd-docs: Deploy to staging documentation site

Manual Deployments

For emergency situations, deployments can be triggered manually by administrators using:

  • GitHub Actions workflows
  • Direct deployment scripts in each project

Emergency Procedures

Critical Production Issues

  1. Immediate Response:

    # Create hotfix branch from main
git checkout main
git pull origin main  
git checkout -b hotfix/critical-issue-description

  2. Quick Fix and Deploy:

    # Make minimal fix
git add .
git commit -m "hotfix: resolve critical issue"
git push origin hotfix/critical-issue-description

  3. Fast-Track PR Review:

    • Create PR to main with "HOTFIX" label
    • Get expedited review (can be single reviewer for critical issues)
    • Merge immediately after approval

  4. Post-Deployment:

    # Create PR to merge hotfix into dev
# Tag the hotfix release
git tag -a v2.0.1 -m "Hotfix release"
git push origin v2.0.1

Rollback Procedures

Application Rollback

  1. Immediate: Revert to previous deployment via hosting platform
  2. Git Revert: Create revert commit and deploy 
    git checkout main
git revert <commit-hash>
git push origin main

Database Rollback

  • Follow project-specific database migration rollback procedures
  • Coordinate with team before executing database rollbacks

Branch Maintenance

Regular Cleanup

Delete Merged Branches

# Delete local merged branches
git branch --merged dev | grep -v "\*\|dev\|main" | xargs -n 1 git branch -d
 
# Delete remote tracking branches
git remote prune origin

Stale Branch Policy

  • Feature/Bugfix branches: Delete after 30 days of inactivity
  • Release branches: Keep for historical reference
  • Hotfix branches: Delete after 90 days

Branch Naming Enforcement

Use Git hooks or GitHub Actions to enforce naming conventions:

  • feature/*
  • bugfix/*
  • release/*
  • hotfix/*

Team Collaboration

Code Review Process

Reviewer Assignment

  • Backend Changes: Assign backend developers
  • Frontend Changes: Assign frontend developers
  • Full-Stack Features: Assign both backend and frontend reviewers
  • Documentation: Assign technical writers or project leads

Review Checklist

  • Code follows project conventions
  • Tests are included and passing
  • Documentation is updated
  • No sensitive information committed
  • Breaking changes are documented
  • Performance impact considered

Conflict Resolution

Merge Conflicts

  1. Prevention: Regularly sync with dev branch
  2. Resolution: Resolve conflicts in feature branch before PR
  3. Assistance: Ask for help from code owners if conflicts are complex

Integration Issues

  • Use feature flags for partially complete features
  • Coordinate with team for breaking changes
  • Test integration points thoroughly

Monitoring and Metrics

Branch Health Metrics

  • Number of open PRs per branch type
  • Average time from PR creation to merge
  • Deployment success rates
  • Hotfix frequency and resolution time

Alerts and Notifications

  • Failed deployments
  • Long-running feature branches (>2 weeks)
  • Critical security vulnerabilities
  • Production errors requiring hotfixes

Best Practices Summary

Do's ✅

  • Always create PRs for changes to dev and main
  • Write clear, descriptive commit messages
  • Test changes thoroughly before creating PRs
  • Keep feature branches small and focused
  • Regularly sync with dev to avoid conflicts
  • Use conventional commit message format
  • Delete merged branches promptly
  • Include relevant stakeholders in PR reviews

Don'ts ❌

  • Never commit directly to main or dev
  • Don't create long-lived feature branches
  • Don't merge PRs without proper review
  • Don't commit sensitive information (API keys, credentials)
  • Don't ignore CI/CD failures
  • Don't create overly broad PRs affecting multiple unrelated areas
  • Don't bypass branch protection rules
  • Don't merge PRs with failing tests

Tools and Automation

Required Tools

  • Git: Version control
  • GitHub CLI: PR management (gh pr create, gh pr merge)
  • Project CLIs: npm, pip, pnpm for project-specific operations

Recommended Extensions

  • VS Code Git Graph: Visualize branch structure
  • GitHub Desktop: GUI for Git operations
  • GitKraken: Advanced Git GUI with conflict resolution

Automation Scripts

Each project includes automation scripts:

  • mtd-ai: ./start_dev.sh, python run_tests.py
  • mtd-web-v2: npm run type-check, npm run build
  • mtd-docs: pnpm build, pnpm dev

Support and Questions

For questions about this branching strategy or Git workflows:

  1. Documentation: Check project-specific CLAUDE.md files
  2. Issues: Create GitHub issue with question label
  3. Team Chat: Use project communication channels
  4. Code Review: Ask during PR review process

This strategy is designed to support the MTD project's multi-team, multi-project development while maintaining code quality and deployment stability. Regular review and updates to this strategy are encouraged as the project evolves.

Getting StartedA2A Protocol Analysis