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
|
||||||
28
README.md
28
README.md
@@ -363,6 +363,34 @@ If a deployment fails but the name is marked as taken:
|
|||||||
|
|
||||||
See `CLAUDE.md` for development guidelines and architecture documentation.
|
See `CLAUDE.md` for development guidelines and architecture documentation.
|
||||||
|
|
||||||
|
## Branching Strategy
|
||||||
|
|
||||||
|
This project uses a Git Flow branching model:
|
||||||
|
|
||||||
|
- **`main`** - Production branch (deployed to https://portal.ai.flexinit.nl)
|
||||||
|
- **`staging`** - Pre-production testing environment
|
||||||
|
- **`dev`** - Active development branch
|
||||||
|
|
||||||
|
### Workflow
|
||||||
|
```
|
||||||
|
feature/xyz → dev → staging → main
|
||||||
|
```
|
||||||
|
|
||||||
|
### Quick Commands
|
||||||
|
```bash
|
||||||
|
# Start new feature
|
||||||
|
git checkout dev
|
||||||
|
git checkout -b feature/my-feature
|
||||||
|
|
||||||
|
# Deploy to staging (via PR)
|
||||||
|
# Create PR: dev → staging
|
||||||
|
|
||||||
|
# Deploy to production (via PR)
|
||||||
|
# Create PR: staging → main
|
||||||
|
```
|
||||||
|
|
||||||
|
See `BRANCHING_STRATEGY.md` for complete workflow documentation.
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
[Your License Here]
|
[Your License Here]
|
||||||
|
|||||||
Reference in New Issue
Block a user