initial setup
This commit is contained in:
631
docs/git_branch_strategy.md
Normal file
631
docs/git_branch_strategy.md
Normal file
@@ -0,0 +1,631 @@
|
||||
# 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.*
|
||||
Reference in New Issue
Block a user