ai-stack-deployer/BRANCHING_STRATEGY.md

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

# 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

# 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

# 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)

# 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:

## 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

# 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:

## [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

# 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

# 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