diff --git a/BRANCHING_STRATEGY.md b/BRANCHING_STRATEGY.md new file mode 100644 index 0000000..e233ded --- /dev/null +++ b/BRANCHING_STRATEGY.md @@ -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 +git push origin main + +# Or use git reset (dangerous - requires force push) +git reset --hard +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 diff --git a/README.md b/README.md index 55bfe7e..b6ce133 100644 --- a/README.md +++ b/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. +## 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 [Your License Here]