Add branching strategy documentation
- Create BRANCHING_STRATEGY.md with Git Flow workflow - Update README.md with branching overview - Document dev → staging → main flow - Include PR guidelines and best practices - Add emergency procedures and rollback instructions
This commit is contained in:
Oussama Douhou
425
BRANCHING_STRATEGY.md
Normal file
425
BRANCHING_STRATEGY.md
Normal file
@@ -0,0 +1,425 @@
|
||||
# Branching Strategy - AI Stack Deployer
|
||||
|
||||
## Overview
|
||||
|
||||
This project follows a **Git Flow** branching strategy with three main branches for proper development, testing, and production workflows.
|
||||
|
||||
## Branch Structure
|
||||
|
||||
```
|
||||
main (production)
|
||||
↑
|
||||
staging (pre-production)
|
||||
↑
|
||||
dev (active development)
|
||||
↑
|
||||
feature branches
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Branch Descriptions
|
||||
|
||||
### 1. `main` - Production Branch
|
||||
|
||||
**Purpose:** Production-ready code deployed to `https://portal.ai.flexinit.nl`
|
||||
|
||||
**Rules:**
|
||||
- ✅ Only merge from `staging` via Pull Request
|
||||
- ✅ All merges must pass CI/CD checks
|
||||
- ✅ Code reviewed and tested
|
||||
- ❌ Never commit directly to `main`
|
||||
- ❌ Never merge from `dev` directly
|
||||
|
||||
**Deployment:** Automatic deployment to production (Dokploy)
|
||||
|
||||
**Protection:**
|
||||
- Requires pull request reviews
|
||||
- Requires status checks to pass
|
||||
- No force pushes allowed
|
||||
|
||||
---
|
||||
|
||||
### 2. `staging` - Pre-Production Branch
|
||||
|
||||
**Purpose:** Final testing environment before production
|
||||
|
||||
**Rules:**
|
||||
- ✅ Merge from `dev` when features are ready for testing
|
||||
- ✅ Test thoroughly in staging environment
|
||||
- ✅ Bug fixes can be made directly on `staging`
|
||||
- ✅ Hotfixes merged to both `staging` and `main`
|
||||
- ❌ Don't commit experimental features
|
||||
|
||||
**Deployment:** Deploys to staging environment (if configured)
|
||||
|
||||
**Testing:**
|
||||
- Integration testing
|
||||
- User acceptance testing (UAT)
|
||||
- Performance testing
|
||||
- Security testing
|
||||
|
||||
---
|
||||
|
||||
### 3. `dev` - Development Branch
|
||||
|
||||
**Purpose:** Active development and integration branch
|
||||
|
||||
**Rules:**
|
||||
- ✅ Merge feature branches here
|
||||
- ✅ Continuous integration testing
|
||||
- ✅ Can have unstable code
|
||||
- ✅ Rebase/squash feature branches before merge
|
||||
- ❌ Don't merge broken code
|
||||
|
||||
**Deployment:** Deploys to development environment
|
||||
|
||||
**Testing:**
|
||||
- Unit tests
|
||||
- Integration tests
|
||||
- Basic functionality tests
|
||||
|
||||
---
|
||||
|
||||
## Workflow Diagram
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ Feature Branch │ (feature/xyz)
|
||||
└────────┬────────┘
|
||||
│
|
||||
│ PR + Review
|
||||
↓
|
||||
┌────────┐
|
||||
│ dev │ (Development)
|
||||
└───┬────┘
|
||||
│
|
||||
│ PR when ready
|
||||
↓
|
||||
┌──────────┐
|
||||
│ staging │ (Pre-production)
|
||||
└────┬─────┘
|
||||
│
|
||||
│ PR after testing
|
||||
↓
|
||||
┌────────┐
|
||||
│ main │ (Production)
|
||||
└────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### 1. Feature Development
|
||||
|
||||
```bash
|
||||
# Start new feature from dev
|
||||
git checkout dev
|
||||
git pull origin dev
|
||||
git checkout -b feature/add-user-dashboard
|
||||
|
||||
# Make changes, commit
|
||||
git add .
|
||||
git commit -m "feat: add user dashboard"
|
||||
|
||||
# Push and create PR to dev
|
||||
git push origin feature/add-user-dashboard
|
||||
# Create PR: feature/add-user-dashboard → dev
|
||||
```
|
||||
|
||||
### 2. Deploy to Staging
|
||||
|
||||
```bash
|
||||
# When dev is stable, merge to staging
|
||||
git checkout staging
|
||||
git pull origin staging
|
||||
git merge dev
|
||||
git push origin staging
|
||||
|
||||
# Or via Pull Request (recommended):
|
||||
# Create PR: dev → staging
|
||||
```
|
||||
|
||||
### 3. Deploy to Production
|
||||
|
||||
```bash
|
||||
# After staging tests pass, merge to main
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git merge staging
|
||||
git push origin main
|
||||
|
||||
# Or via Pull Request (recommended):
|
||||
# Create PR: staging → main
|
||||
```
|
||||
|
||||
### 4. Hotfix (Emergency Production Fix)
|
||||
|
||||
```bash
|
||||
# Create hotfix from main
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git checkout -b hotfix/critical-bug
|
||||
|
||||
# Fix bug, commit
|
||||
git add .
|
||||
git commit -m "fix: critical security issue"
|
||||
|
||||
# Merge to both staging and main
|
||||
git checkout staging
|
||||
git merge hotfix/critical-bug
|
||||
git push origin staging
|
||||
|
||||
git checkout main
|
||||
git merge hotfix/critical-bug
|
||||
git push origin main
|
||||
|
||||
# Back-merge to dev
|
||||
git checkout dev
|
||||
git merge main
|
||||
git push origin dev
|
||||
|
||||
# Delete hotfix branch
|
||||
git branch -d hotfix/critical-bug
|
||||
git push origin --delete hotfix/critical-bug
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Branch Naming Conventions
|
||||
|
||||
### Feature Branches
|
||||
- `feature/add-authentication`
|
||||
- `feature/update-ui-design`
|
||||
- `feature/new-api-endpoint`
|
||||
|
||||
### Bugfix Branches
|
||||
- `bugfix/fix-validation-error`
|
||||
- `bugfix/correct-typo`
|
||||
|
||||
### Hotfix Branches
|
||||
- `hotfix/security-patch`
|
||||
- `hotfix/critical-crash`
|
||||
|
||||
### Refactor Branches
|
||||
- `refactor/cleanup-api-client`
|
||||
- `refactor/improve-performance`
|
||||
|
||||
---
|
||||
|
||||
## Pull Request Guidelines
|
||||
|
||||
### Creating a PR
|
||||
|
||||
**Title Format:**
|
||||
```
|
||||
[TYPE] Brief description
|
||||
|
||||
Examples:
|
||||
- [FEATURE] Add user authentication
|
||||
- [BUGFIX] Fix validation error
|
||||
- [HOTFIX] Critical security patch
|
||||
- [REFACTOR] Cleanup API client
|
||||
```
|
||||
|
||||
**Description Template:**
|
||||
```markdown
|
||||
## Changes
|
||||
- List what was changed
|
||||
|
||||
## Testing
|
||||
- How was this tested?
|
||||
- What test cases were added?
|
||||
|
||||
## Screenshots (if UI changes)
|
||||
- Before/after screenshots
|
||||
|
||||
## Checklist
|
||||
- [ ] Tests pass
|
||||
- [ ] TypeScript compiles
|
||||
- [ ] Docker builds successfully
|
||||
- [ ] No console errors
|
||||
- [ ] Code reviewed
|
||||
```
|
||||
|
||||
### Review Checklist
|
||||
|
||||
Before approving a PR:
|
||||
- ✅ Code follows project conventions
|
||||
- ✅ Tests pass (automated CI checks)
|
||||
- ✅ TypeScript compiles without errors
|
||||
- ✅ No security vulnerabilities introduced
|
||||
- ✅ Documentation updated if needed
|
||||
- ✅ No breaking changes (or documented)
|
||||
|
||||
---
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### Automated Checks
|
||||
|
||||
**On every PR:**
|
||||
- `bun run typecheck` - TypeScript validation
|
||||
- `bun run build` - Build verification
|
||||
- Docker build test
|
||||
- Linting (if configured)
|
||||
|
||||
**On merge to `main`:**
|
||||
- Full build
|
||||
- Docker image build and push
|
||||
- Automatic deployment to production
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Each branch should have its own environment configuration:
|
||||
|
||||
```
|
||||
main → .env.production
|
||||
staging → .env.staging
|
||||
dev → .env.development
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### DO:
|
||||
- ✅ Keep commits atomic and focused
|
||||
- ✅ Write clear commit messages
|
||||
- ✅ Rebase feature branches before merging
|
||||
- ✅ Squash small fixup commits
|
||||
- ✅ Tag production releases (`v1.0.0`, `v1.1.0`)
|
||||
- ✅ Delete merged feature branches
|
||||
- ✅ Pull latest changes before creating new branch
|
||||
|
||||
### DON'T:
|
||||
- ❌ Commit directly to `main` or `staging`
|
||||
- ❌ Force push to protected branches
|
||||
- ❌ Merge without review
|
||||
- ❌ Push broken code to `dev`
|
||||
- ❌ Leave feature branches unmerged for weeks
|
||||
- ❌ Mix multiple features in one branch
|
||||
|
||||
---
|
||||
|
||||
## Release Management
|
||||
|
||||
### Semantic Versioning
|
||||
|
||||
Follow semver: `MAJOR.MINOR.PATCH`
|
||||
|
||||
- **MAJOR**: Breaking changes
|
||||
- **MINOR**: New features (backward compatible)
|
||||
- **PATCH**: Bug fixes
|
||||
|
||||
### Tagging Releases
|
||||
|
||||
```bash
|
||||
# After merging to main
|
||||
git checkout main
|
||||
git pull origin main
|
||||
|
||||
# Tag the release
|
||||
git tag -a v1.0.0 -m "Release v1.0.0: React migration complete"
|
||||
git push origin v1.0.0
|
||||
```
|
||||
|
||||
### Changelog
|
||||
|
||||
Update `CHANGELOG.md` on every release:
|
||||
|
||||
```markdown
|
||||
## [1.0.0] - 2026-01-13
|
||||
|
||||
### Added
|
||||
- React migration with WebGL background
|
||||
- i18n support (EN/NL/AR)
|
||||
- Comprehensive test suite
|
||||
|
||||
### Changed
|
||||
- Redesigned deploy page UI
|
||||
- Code-split Three.js bundle
|
||||
|
||||
### Fixed
|
||||
- Docker build issues
|
||||
- Missing dependencies
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Branch Protection Rules (Recommended)
|
||||
|
||||
### For `main` branch:
|
||||
- Require pull request before merging
|
||||
- Require 1+ approvals
|
||||
- Require status checks to pass
|
||||
- Require conversation resolution before merging
|
||||
- No force pushes
|
||||
- No deletions
|
||||
|
||||
### For `staging` branch:
|
||||
- Require pull request before merging
|
||||
- Require status checks to pass
|
||||
- No force pushes
|
||||
|
||||
### For `dev` branch:
|
||||
- Require status checks to pass (optional)
|
||||
- Allow force pushes (for rebasing)
|
||||
|
||||
---
|
||||
|
||||
## Emergency Procedures
|
||||
|
||||
### Rollback Production
|
||||
|
||||
```bash
|
||||
# Find last good commit
|
||||
git log main --oneline
|
||||
|
||||
# Revert to last good state
|
||||
git checkout main
|
||||
git revert <bad-commit-hash>
|
||||
git push origin main
|
||||
|
||||
# Or use git reset (dangerous - requires force push)
|
||||
git reset --hard <last-good-commit>
|
||||
git push --force-with-lease origin main
|
||||
```
|
||||
|
||||
### Broken Staging
|
||||
|
||||
```bash
|
||||
# Reset staging to match main
|
||||
git checkout staging
|
||||
git reset --hard main
|
||||
git push --force-with-lease origin staging
|
||||
|
||||
# Then merge dev again (after fixing issues)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Command |
|
||||
|------|---------|
|
||||
| Start new feature | `git checkout dev && git checkout -b feature/xyz` |
|
||||
| Update feature branch | `git checkout feature/xyz && git rebase dev` |
|
||||
| Merge to dev | Create PR: `feature/xyz → dev` |
|
||||
| Deploy to staging | Create PR: `dev → staging` |
|
||||
| Deploy to production | Create PR: `staging → main` |
|
||||
| Emergency hotfix | `git checkout main && git checkout -b hotfix/xyz` |
|
||||
| Tag release | `git tag -a v1.0.0 -m "message"` |
|
||||
| Delete merged branch | `git branch -d feature/xyz && git push origin --delete feature/xyz` |
|
||||
|
||||
---
|
||||
|
||||
## Contact & Support
|
||||
|
||||
For questions about the branching strategy:
|
||||
- Review this document
|
||||
- Ask in team chat
|
||||
- Check Git Flow documentation: https://nvie.com/posts/a-successful-git-branching-model/
|
||||
|
||||
**Last Updated:** 2026-01-13
|
||||
Reference in New Issue
Block a user