job-forge/docs/git_branch_strategy.md

JobForge MVP - Git Branch Management Strategy

Version: 1.0.0 MVP
Repository: Single monorepo approach
Platform: Gitea
Target Audience: Development Team
Last Updated: July 2025

---

🎯 Branching Strategy Overview

Repository Structure

Single Monorepo containing:

• Frontend (Dash + Mantine)
• Backend (FastAPI)
• Database schemas and migrations
• Docker configuration
• Documentation
• Tests

Core Branching Model

main (production-ready)
├── develop (integration branch)
│   ├── feature/user-authentication
│   ├── feature/job-application-crud
│   ├── feature/ai-research-agent
│   ├── feature/resume-optimization
│   └── feature/cover-letter-generator
├── hotfix/critical-security-patch
└── release/v1.0.0-mvp

---

🌿 Branch Types & Purposes

1. main (Production Branch)

• Purpose: Production-ready code only
• Protection: Fully protected, requires PR approval
• Deployment: Auto-deploys to production environment
• Merge Strategy: Squash and merge from release branches only

Rules:

• No direct commits allowed
• All changes via Pull Request from develop or hotfix/*
• Must pass all CI/CD checks
• Requires at least 1 code review approval
• Must be deployable at any time

2. develop (Integration Branch)

• Purpose: Integration of completed features
• Protection: Protected, requires PR approval
• Deployment: Auto-deploys to staging environment
• Merge Strategy: Merge commits to preserve feature history

Rules:

• All feature branches merge here first
• Continuous integration testing
• Regular merges to main for releases
• Should be stable enough for testing

3. feature/ (Feature Development)

• Purpose: Individual feature development
• Naming: feature/[component]-[description]
• Lifecycle: Created from develop, merged back to develop
• Protection: Optional, team discretion

Examples:

feature/backend-user-authentication
feature/frontend-application-sidebar  
feature/ai-claude-integration
feature/database-rls-policies
feature/docker-development-setup

4. hotfix/ (Emergency Fixes)

• Purpose: Critical production issues
• Naming: hotfix/[issue-description]
• Lifecycle: Created from main, merged to both main and develop
• Priority: Highest priority, fast-track review

5. release/ (Release Preparation)

• Purpose: Prepare releases, final testing
• Naming: release/v[version]
• Lifecycle: Created from develop, merged to main when ready
• Activities: Bug fixes, documentation updates, version bumps

---

🔄 Development Workflow

Standard Feature Development Flow

1. Start New Feature

# Ensure develop is up to date
git checkout develop
git pull origin develop

# Create feature branch
git checkout -b feature/backend-application-service
git push -u origin feature/backend-application-service

2. Development Cycle

# Regular commits with descriptive messages
git add .
git commit -m "feat(backend): implement application creation endpoint

- Add POST /api/v1/applications endpoint
- Implement application validation
- Add database integration
- Include unit tests

Closes #23"

# Push regularly to backup work
git push origin feature/backend-application-service

3. Feature Completion

# Update with latest develop changes
git checkout develop
git pull origin develop
git checkout feature/backend-application-service
git rebase develop

# Push updated branch
git push origin feature/backend-application-service --force-with-lease

# Create Pull Request via Gitea UI

4. Code Review & Merge

• Create PR from feature branch to develop
• Code review by at least 1 team member
• CI/CD checks must pass (tests, linting, etc.)
• Merge using "Merge commit" strategy
• Delete feature branch after merge

---

📋 Pull Request Guidelines

PR Title Format

[type](scope): brief description

Examples:
feat(backend): add user authentication endpoints
fix(frontend): resolve sidebar navigation bug  
docs(api): update endpoint documentation
test(database): add RLS policy tests

PR Description Template

## 🎯 Purpose
Brief description of what this PR accomplishes.

## 🔧 Changes Made
- [ ] Add new API endpoint for application creation
- [ ] Implement database integration
- [ ] Add unit tests with 90% coverage
- [ ] Update API documentation

## 🧪 Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed
- [ ] Database migrations tested

## 📚 Documentation
- [ ] API documentation updated
- [ ] README updated if needed
- [ ] Code comments added for complex logic

## 🔍 Review Checklist
- [ ] Code follows project style guidelines
- [ ] No hardcoded secrets or credentials
- [ ] Error handling implemented
- [ ] Security considerations addressed

## 🔗 Related Issues
Closes #123
Relates to #456

Review Criteria

Mandatory Checks:

• All CI/CD pipeline checks pass
• No merge conflicts with target branch
• At least 1 peer code review approval
• Tests cover new functionality
• Documentation updated

Code Quality Checks:

• Follows established coding standards
• No security vulnerabilities introduced
• Performance considerations addressed
• Error handling implemented properly

---

🚀 Release Management

MVP Release Strategy

Phase 1 Releases (Weeks 1-8)

v0.1.0 - Week 2: Basic infrastructure
v0.2.0 - Week 4: User auth + application CRUD
v0.3.0 - Week 6: AI agents integration  
v1.0.0 - Week 8: Complete MVP

Release Process

1. Create Release Branch

git checkout develop
git pull origin develop
git checkout -b release/v1.0.0-mvp
git push -u origin release/v1.0.0-mvp

2. Prepare Release

• Update version numbers in package files
• Update CHANGELOG.md
• Final testing and bug fixes
• Documentation review

3. Release to Production

# Create PR: release/v1.0.0-mvp → main
# After approval and merge:
git checkout main
git pull origin main
git tag -a v1.0.0 -m "MVP Release v1.0.0"
git push origin v1.0.0

4. Post-Release Cleanup

# Merge changes back to develop
git checkout develop
git merge main
git push origin develop

# Delete release branch
git branch -d release/v1.0.0-mvp
git push origin --delete release/v1.0.0-mvp

---

🔒 Branch Protection Rules

main Branch Protection

Protection Rules:
  - Require pull request reviews: true
  - Required approving reviews: 1
  - Dismiss stale reviews: true
  - Require review from code owners: true
  - Restrict pushes to admins only: true
  - Require status checks: true
  - Required status checks:
    - ci/backend-tests
    - ci/frontend-tests  
    - ci/integration-tests
    - ci/security-scan
  - Require branches to be up to date: true
  - Include administrators: true

develop Branch Protection

Protection Rules:
  - Require pull request reviews: true
  - Required approving reviews: 1
  - Require status checks: true
  - Required status checks:
    - ci/backend-tests
    - ci/frontend-tests
    - ci/lint-check
  - Require branches to be up to date: true

---

🤖 CI/CD Integration

Automated Workflows by Branch

feature/* branches

# .gitea/workflows/feature.yml
on:
  push:
    branches: 
      - 'feature/*'
  pull_request:
    branches:
      - develop

jobs:
  - lint-and-format
  - unit-tests
  - security-scan
  - build-check

develop branch

# .gitea/workflows/develop.yml
on:
  push:
    branches:
      - develop

jobs:
  - lint-and-format
  - unit-tests
  - integration-tests
  - security-scan
  - build-and-deploy-staging

main branch

# .gitea/workflows/production.yml
on:
  push:
    branches:
      - main
    tags:
      - 'v*'

jobs:
  - full-test-suite
  - security-scan
  - build-and-deploy-production
  - create-release-notes

---

📊 Development Team Workflow

Team Roles & Responsibilities

Backend Developer

# Typical feature branches:
feature/backend-auth-service
feature/backend-application-api
feature/backend-ai-integration
feature/database-schema-updates

Frontend Developer

# Typical feature branches:
feature/frontend-auth-components
feature/frontend-application-dashboard
feature/frontend-document-editor
feature/ui-component-library

Full-Stack Developer

# End-to-end feature branches:
feature/complete-user-registration
feature/complete-application-workflow
feature/complete-document-management

DevOps/Infrastructure

# Infrastructure branches:
feature/docker-optimization
feature/ci-cd-pipeline
feature/monitoring-setup
feature/deployment-automation

Daily Development Routine

Morning Sync

# Start each day with latest changes
git checkout develop
git pull origin develop

# Update feature branch
git checkout feature/your-current-feature
git rebase develop

# Resolve any conflicts and continue work

End of Day

# Commit and push daily progress
git add .
git commit -m "wip: progress on application service implementation"
git push origin feature/your-current-feature

---

🐛 Handling Common Scenarios

Scenario 1: Feature Branch Behind develop

# Update feature branch with latest develop
git checkout feature/your-feature
git rebase develop

# If conflicts occur:
git status                    # See conflicted files
# Edit files to resolve conflicts
git add .
git rebase --continue

# Force push with lease (safer than --force)
git push origin feature/your-feature --force-with-lease

Scenario 2: Emergency Hotfix

# Create hotfix from main
git checkout main
git pull origin main
git checkout -b hotfix/critical-security-fix

# Make fix
git add .
git commit -m "fix: resolve critical authentication vulnerability

- Patch JWT token validation
- Update security tests
- Add rate limiting

Fixes #emergency-issue"

# Push and create PRs to both main and develop
git push -u origin hotfix/critical-security-fix

# Create PR: hotfix/critical-security-fix → main (priority)
# Create PR: hotfix/critical-security-fix → develop

Scenario 3: Large Feature Coordination

# For complex features requiring multiple developers:

# Main feature branch
feature/ai-agents-integration

# Sub-feature branches
feature/ai-agents-integration/research-agent
feature/ai-agents-integration/resume-optimizer
feature/ai-agents-integration/cover-letter-generator

# Merge sub-features to main feature branch first
# Then merge main feature branch to develop

---

📈 Branch Management Best Practices

DO's ✅

• Keep branches focused - One feature per branch
• Use descriptive names - Clear what the branch does
• Regular commits - Small, focused commits with good messages
• Rebase before merge - Keep history clean
• Delete merged branches - Avoid branch pollution
• Test before merge - Ensure CI/CD passes
• Review code thoroughly - Maintain code quality

DON'Ts ❌

• Don't commit directly to main - Always use PR workflow
• Don't use generic branch names - Avoid "fix", "update", "changes"
• Don't let branches go stale - Merge or close unused branches
• Don't ignore conflicts - Resolve properly, don't force
• Don't skip testing - Every merge should be tested
• Don't merge your own PRs - Always get peer review

Naming Conventions

# Good branch names:
feature/backend-user-authentication
feature/frontend-application-sidebar
feature/ai-claude-integration
feature/database-migration-v2
hotfix/security-jwt-validation
release/v1.0.0-mvp

# Bad branch names:
fix-stuff
john-updates
temporary
new-feature
test-branch

---

🔧 Git Configuration

Recommended Git Settings

# Set up git aliases for common operations
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.st status
git config --global alias.unstage 'reset HEAD --'
git config --global alias.last 'log -1 HEAD'
git config --global alias.visual '!gitk'

# Better log formatting
git config --global alias.lg "log --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

# Set up pull to rebase by default (cleaner history)
git config --global pull.rebase true

# Set up push to current branch only
git config --global push.default current

Team .gitignore

# Environment files
.env
.env.local
.env.*.local

# IDE files
.vscode/
.idea/
*.swp
*.swo

# OS files
.DS_Store
Thumbs.db

# Docker
.dockerignore

# Python
__pycache__/
*.pyc
*.pyo
*.pyd
.Python
env/
venv/
ENV/

# Node modules (if using)
node_modules/

# Logs
*.log
logs/

# Database
*.db
*.sqlite

# Temporary files
*.tmp
*.temp
temp/
tmp/

# Coverage reports
htmlcov/
.coverage
.coverage.*

# Test outputs
.pytest_cache/
.tox/

---

📚 Integration with Development Documents

Relationship to Other Documents

• Development Setup: Clone from correct branch, set up environment
• API Specification: Feature branches should implement specific endpoints
• Database Design: Schema changes require migration planning
• Testing Strategy: All branches must pass defined test suites

8-Week MVP Timeline Integration

Week 1-2: Foundation
├── feature/docker-development-setup
├── feature/database-initial-schema
└── feature/backend-project-structure

Week 3-4: Core Features  
├── feature/backend-user-authentication
├── feature/frontend-auth-components
└── feature/backend-application-crud

Week 5-6: AI Integration
├── feature/ai-claude-integration
├── feature/ai-research-agent
└── feature/ai-resume-optimizer

Week 7-8: Polish & Release
├── feature/frontend-document-editor
├── feature/error-handling-improvements
└── release/v1.0.0-mvp

---

This Git branching strategy ensures clean, maintainable code while supporting parallel development and safe deployments for the JobForge MVP. The strategy scales from MVP development to future SaaS features.