Skip to content

ADR: Branching Strategy & Gating

Status

ACCEPTED

Context

Previously, the system used a mix of development, testing, and main branches, where testing was often confused with an activity rather than an environment. This led to "tribal knowledge" requirements to map branches to environments.

Decision

We adopt a Strict 3-Tier Branching Model that maps 1:1 with our Environment Strategy.

1. Branch Naming

  • dev: The active development stream (maps to DEV).
  • stg: The staging/integration stream (maps to STG).
  • main: The production stream (maps to PRD).

2. The Migration

  • The testing branch is DEPRECATED and removed.
  • The stg branch replaces it as the canonical Tier 2 branch.

3. Gating Logic

Testing is an activity, not a branch name. - Staging Gate: Code merged to stg automatically triggers the "Verification" suite (Tests, Linting, Builds). - Preview Gate: Code on stg is deployed to the Staging Environment for human review.

Consequences

  • Positive: Clearer mental model (stg = Staging).
  • Positive: Industry standard naming (main vs master, stg vs test).
  • Negative: One-time cost to update CI/CD workflows (Completed).

Enforcement

  • CI/CD: Workflows only trigger on stg, dev, main.
  • AI: Agents are instructed via .cursorrules to only recognize this path.