Branch Strategy

This document outlines the Git branching strategy used in the Aitana frontend project.

Branch Overview

The project uses a three-branch deployment strategy with environment-specific branches:

feature branches → dev → test → prod
                       ↘ docs (website updates)

Core Branches

dev (Development)

  • Purpose: Main development branch
  • Environment: Internal development
  • Protection: Minimal - allows direct commits for small changes
  • Merge Strategy: Fast-forward or merge commits
  • CI/CD: No automatic deployment

Usage:

# Create feature branch from dev
git checkout dev
git pull origin dev
git checkout -b feature/my-new-feature

# Or commit directly for small changes
git checkout dev
git add .
git commit -m "fix: minor bug fix"
git push origin dev

test (Testing/Staging)

  • Purpose: Pre-production testing environment
  • Environment: https://ai2.aitana.chat
  • Protection: Pull Request required
  • Merge Strategy: Auto-merge after CI passes
  • CI/CD: Automatic deployment on successful merge

Usage:

# Create PR from dev to test
git checkout dev
git pull origin dev
# Create PR via GitHub UI: dev → test

prod (Production)

  • Purpose: Live production environment
  • Environment: https://ai.aitana.chat
  • Protection: Pull Request + Manual review required
  • Merge Strategy: Manual merge after approval
  • CI/CD: Automatic deployment after manual approval

Usage:

# After successful testing on ai2.aitana.chat
# Create PR via GitHub UI: test → prod
# Requires manual review and approval

docs (Documentation Website)

  • Purpose: GitHub Pages documentation site
  • Environment: Documentation website
  • Protection: Pull Request required
  • Merge Strategy: Manual merge
  • CI/CD: GitHub Pages deployment

Usage:

# Update documentation website
# Create PR via GitHub UI: dev → docs

Feature Branch Strategy

Feature Branch Naming

feature/description-of-feature
bugfix/description-of-bug
hotfix/critical-fix-description
chore/maintenance-task

Feature Branch Lifecycle

  1. Create from dev: 
    git checkout dev
git pull origin dev
git checkout -b feature/user-authentication
  2. Develop and test locally: 
    # Make changes
git add .
git commit -m "feat: add user authentication"
   
# Run quality checks
npm run quality:check
  3. Push and create PR to dev: 
    git push origin feature/user-authentication
# Create PR via GitHub UI: feature/user-authentication → dev
  4. After merge, clean up: 
    git checkout dev
git pull origin dev
git branch -d feature/user-authentication

Deployment Flow

Normal Development Flow

1. feature/xyz → dev (PR review)
2. dev → test (auto-merge after CI)
3. Manual testing on ai2.aitana.chat
4. test → prod (manual review + approval)

Hotfix Flow

1. hotfix/critical-fix → dev (expedited review)
2. dev → test (immediate auto-merge)
3. Minimal testing on ai2.aitana.chat
4. test → prod (expedited approval)

Documentation Flow

1. Update docs in feature branch
2. feature/docs-update → dev
3. dev → docs (for website updates)

Branch Protection Rules

dev Branch

  • ✅ Allow direct pushes (for small changes)
  • ✅ Allow force pushes (with caution)
  • ✅ Require CI checks for PRs
  • ❌ Require PR reviews (optional for efficiency)

test Branch

  • ❌ No direct pushes
  • ❌ No force pushes
  • ✅ Require PR from dev
  • ✅ Require CI checks to pass
  • ✅ Auto-merge when CI passes
  • ✅ Require up-to-date branch

prod Branch

  • ❌ No direct pushes
  • ❌ No force pushes
  • ✅ Require PR from test
  • ✅ Require CI checks to pass
  • ✅ Require manual review
  • ✅ Require administrator approval
  • ✅ Require up-to-date branch

docs Branch

  • ❌ No direct pushes
  • ✅ Require PR from dev
  • ✅ Require review for documentation changes

CI/CD Integration

Automated Triggers

| Branch | Trigger | Action | |——–|———|——–| | dev | Push | No deployment, quality checks only | | test | PR merge | Automatic deployment to ai2.aitana.chat | | prod | PR merge | Automatic deployment to ai.aitana.chat | | docs | PR merge | GitHub Pages deployment |

Quality Gates

All branches require:

  • ✅ ESLint passing
  • ✅ TypeScript compilation
  • ✅ Frontend tests passing
  • ✅ Backend test suites passing
  • ✅ Docker build success
  • ✅ Coverage requirements met

Emergency Procedures

Critical Hotfix

  1. Create hotfix branch from current prod
  2. Apply minimal fix
  3. Fast-track through: hotfix → dev → test → prod
  4. Skip extensive testing for critical issues

Rollback Procedure

  1. Identify last known good commit
  2. Create rollback branch from good commit
  3. Emergency PR to prod
  4. Bypass normal review for critical rollbacks

Branch Recovery

If a branch becomes corrupted:

# Reset to last known good state
git checkout problematic-branch
git reset --hard origin/last-known-good-commit
git push --force-with-lease origin problematic-branch

Best Practices

Commit Messages

Follow conventional commits:

feat: add new feature
fix: resolve bug
docs: update documentation
chore: maintenance task
test: add tests
refactor: code refactoring

Pull Request Guidelines

  • ✅ Clear title and description
  • ✅ Link to related issues
  • ✅ Include testing instructions
  • ✅ Add screenshots for UI changes
  • ✅ Update documentation if needed

Code Review

  • 🔍 Focus on logic and architecture
  • 🔍 Check test coverage
  • 🔍 Verify security implications
  • 🔍 Ensure documentation updates

Troubleshooting

Common Issues

  1. CI fails on test: Check CI/CD Workflow
  2. Merge conflicts: Rebase on target branch before PR
  3. Failed deployments: Check Cloud Build logs
  4. Coverage drops: Add tests before merging

Recovery Commands

# Sync with remote
git fetch --all

# Reset local branch to remote
git reset --hard origin/branch-name

# Clean working directory
git clean -fd