631 lines
14 KiB
Markdown
631 lines
14 KiB
Markdown
# 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.* |