ADR-007: Git Workflow and Branch Strategy

Date: 2026-01-23 Status: Accepted Deciders: Founder

Context

We need a Git workflow that:

  • Protects production deployments
  • Enables rapid development
  • Supports code review
  • Allows testing before production
  • Scales with team growth
  • Enforces quality standards

Decision

Implement a three-tier branch strategy with protected branches and enforced commit standards.

Branch Structure

main (production)
├── staging (pre-production)
├── develop (integration)
└── feature/*, fix/*, hotfix/* (short-lived)

Branch Purposes

  • main: Production code only, auto-deploys to cairl.com
  • staging: Pre-production testing, deployed to staging subdomain
  • develop: Active development, deployed to dev subdomain
  • feature/*: New features, deployed to preview URLs
  • fix/*: Bug fixes, deployed to preview URLs
  • hotfix/*: Emergency production fixes, fast-track to main

Protection Rules

main branch:

  • Require PR with 1 approval
  • Require status checks (lint, type-check, build)
  • No force pushes
  • No deletions
  • Linear history only

staging and develop:

  • Require PR (self-merge allowed)
  • Require status checks
  • No force pushes
  • No deletions

Commit Standards

Use Conventional Commits format:

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

Enforced via Husky + Commitlint.

Consequences

Positive

  • Quality gates: Code must pass checks before merge
  • Review process: Catches bugs before production
  • Deployment safety: Staging environment for testing
  • Clear workflow: Everyone follows same process
  • Audit trail: All changes are PR-based and reviewable
  • Rollback capability: Easy to revert changes
  • Scalable: Works for solo developer or team

Negative

  • Slower deployments: Must go through PR process
  • More overhead: Creating branches and PRs takes time
  • Merge conflicts: More branches = more potential conflicts
  • Learning curve: Team must learn workflow

Neutral

  • Requires GitHub Actions for CI
  • Requires Vercel for preview deployments
  • Solo developer needs discipline to follow process

Alternatives Considered

1. Trunk-Based Development (main only)

Pros:

  • Simplest workflow
  • No merge conflicts
  • Fastest deployment

Cons:

  • No code review
  • No quality gates
  • Can't test before production
  • High risk of breaking production

Why rejected: Too risky for production system handling sensitive data.

2. GitFlow (more complex branching)

Pros:

  • Very structured
  • Handles releases well
  • Multiple environments

Cons:

  • Overly complex for small team
  • More overhead
  • Slower development

Why rejected: Too complex for startup velocity.

3. Feature Flags Instead of Branches

Pros:

  • Deploy incomplete features
  • A/B testing
  • Easy rollback

Cons:

  • Adds code complexity
  • Still need branches for development
  • Feature flag management overhead

Why rejected: Can add feature flags later, doesn't replace branch strategy.

Implementation

Tools

  • Husky: Git hooks for commit validation
  • Commitlint: Enforce commit message format
  • Lint-staged: Run checks on staged files only
  • GitHub Actions: CI/CD automation
  • Vercel: Deployment automation

Rollout Plan

  1. ✅ Create branch structure
  2. ✅ Install commit tools (Husky, Commitlint)
  3. ✅ Configure GitHub Actions
  4. ⏳ Set up branch protection (manual in GitHub)
  5. ⏳ Document workflow
  6. ⏳ Train team (when hired)

References