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

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