# 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
```bash
# 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
```bash
# 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
```bash
# 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
```markdown
## 🎯 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**
```bash
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**
```bash
# 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**
```bash
# 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
```yaml
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
```yaml
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
```yaml
# .gitea/workflows/feature.yml
on:
  push:
    branches: 
      - 'feature/*'
  pull_request:
    branches:
      - develop

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

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

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

#### main branch
```yaml
# .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**
```bash
# Typical feature branches:
feature/backend-auth-service
feature/backend-application-api
feature/backend-ai-integration
feature/database-schema-updates
```

#### **Frontend Developer**
```bash
# Typical feature branches:
feature/frontend-auth-components
feature/frontend-application-dashboard
feature/frontend-document-editor
feature/ui-component-library
```

#### **Full-Stack Developer** 
```bash
# End-to-end feature branches:
feature/complete-user-registration
feature/complete-application-workflow
feature/complete-document-management
```

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

### Daily Development Routine

#### Morning Sync
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```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.*