CAIRL Git Workflow

Branch Strategy

main (production)           ← cairl.com
├── staging                 ← Pre-production testing
├── develop                 ← Active development
└── feature/*, fix/*, etc.  ← Short-lived branches

Branch Rules

Branch Purpose Deploy To Protection
main Production code cairl.com ✅ Protected
staging Pre-production testing staging subdomain ✅ Protected
develop Active development dev subdomain ✅ Protected
feature/* New features Preview deployments ❌ No protection
fix/* Bug fixes Preview deployments ❌ No protection
hotfix/* Emergency fixes Preview → main ❌ No protection

Daily Workflow

Starting New Work

# Always start from develop
git checkout develop
git pull origin develop

# Create feature branch
git checkout -b feature/user-dashboard

Making Commits

# Stage changes
git add .

# Commit with conventional format
git commit -m "feat(dashboard): add user statistics card"

# Husky will validate commit message and run checks

Commit Message Format

<type>(<scope>): <subject>

<body> (optional)

<footer> (optional)

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation
  • style: Formatting
  • refactor: Code refactoring
  • perf: Performance improvement
  • test: Tests
  • chore: Maintenance
  • ci: CI/CD changes
  • revert: Revert previous commit

Scopes:

  • auth: Authentication
  • verification: ID verification
  • email: Email aliases
  • phone: Phone masking
  • cards: Virtual cards
  • oauth: OAuth provider
  • api: API routes
  • db: Database
  • ui: UI components
  • config: Configuration

Examples:

feat(auth): add email verification flow
fix(waitlist): prevent duplicate submissions
docs(readme): update setup instructions
chore(deps): upgrade next to 14.1.0

Creating Pull Request

  1. Push your branch: git push -u origin feature/user-dashboard
  2. Go to GitHub → Pull Requests → New
  3. Base: develop ← Compare: feature/user-dashboard
  4. Fill out PR template
  5. Wait for CI checks to pass
  6. Merge when approved

Promoting to Staging

# Create PR: develop → staging
# Test on staging deployment
# If good, promote to main

Promoting to Production

# Create PR: staging → main
# Requires approval
# Auto-deploys to cairl.com

Hotfix Process (Emergency Only)

# Create from main
git checkout main
git pull origin main
git checkout -b hotfix/critical-security-patch

# Make fix
git add .
git commit -m "fix(auth): patch session vulnerability"

# Create PR to main
git push -u origin hotfix/critical-security-patch

# After merge to main, backport to develop
git checkout develop
git merge main
git push origin develop

Branch Protection Rules

Main Branch Protection

  • ✅ Require pull request before merging
  • ✅ Require 1 approval
  • ✅ Require status checks to pass
    • CI (lint, type-check, build)
    • Vercel deployment preview
  • ✅ Require conversation resolution
  • ✅ Require linear history
  • ❌ No force pushes
  • ❌ No deletions

Staging & Develop Protection

  • ✅ Require pull request before merging
  • ⚠️ Approvals: 0 (self-merge allowed)
  • ✅ Require status checks to pass
  • ❌ No force pushes
  • ❌ No deletions

Vercel Deployments

Branch Deployment
main cairl.com (production)
staging cairl-git-staging.vercel.app
develop cairl-git-develop.vercel.app
feature/* cairl-git-[branch].vercel.app

Every PR gets a preview deployment with unique URL.

Common Commands

# Check current branch
git branch

# See all branches
git branch -a

# Switch branch
git checkout develop

# Update current branch
git pull origin develop

# Sync feature branch with develop
git checkout feature/my-feature
git merge develop

# Delete local branch
git branch -d feature/completed-feature

# Delete remote branch
git push origin --delete feature/completed-feature

# View commit history
git log --oneline --graph --all

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Stash changes
git stash
git stash pop

Troubleshooting

"Commit message doesn't follow format"

Your commit message must follow conventional commits format:

# ❌ Wrong
git commit -m "fixed bug"

# ✅ Correct
git commit -m "fix(api): resolve null pointer in verification"

"Lint errors prevent commit"

Fix linting errors:

npm run lint
npm run format

Then try commit again.

"Type check failed"

Fix TypeScript errors:

npm run type-check

"Branch is behind main"

Update your branch:

git checkout develop
git pull origin main
git push origin develop

"Merge conflicts"

git checkout feature/my-feature
git merge develop

# Fix conflicts in editor
git add .
git commit -m "chore: resolve merge conflicts"

Best Practices

  1. Pull before you start: Always git pull before creating new branches
  2. Commit often: Small, focused commits are better than large ones
  3. Descriptive messages: Future you will thank present you
  4. Test before PR: Run npm run lint && npm run type-check before pushing
  5. Review your own code: Read your diff before creating PR
  6. Keep branches short-lived: Merge within 1-2 days to avoid conflicts
  7. Delete merged branches: Keep repo clean
  8. Never force push: Especially to protected branches
  9. Use meaningful branch names: feature/user-auth not feature/stuff
  10. Follow the workflow: No shortcuts to main

Getting Help

  • Check this document first
  • Read error messages carefully
  • Ask in team chat
  • Review recent PRs for examples