Skip to content

Release strategy

Status: Accepted — ADR-0007. Automation tracked under Epic F #51.

Companion: Branching · Deployment · PROD runbook

Goals

  1. develop stays the fast integration channel.
  2. PROD only ships from an explicit release/x.y.z cut.
  3. main is the record of what shipped, not the first cut for PROD.
  4. Every production ship gets a git tag + GitHub Release on the main SHA.

Versioning

  • Semver branches: release/1.4.0 → tag v1.4.0.
  • Patch hotfixes: release/1.4.1 → v1.4.1.
  • Prefer Conventional Commits in squash messages for readable release notes.

Happy path

  1. Work lands on develop via PRs from feature/TASK-* (CI green).
  2. Release owner cuts release/x.y.z from develop.
  3. Freeze: only cherry-picks / release fixes on that branch.
  4. Manual PROD deploy from release/x.y.z (see deployment).
  5. Validate PROD (smoke; payment checks as applicable).
  6. Open PR release/x.y.z → main; merge after checks.
  7. Automation creates vX.Y.Z + GitHub Release on the main SHA (F.5 #59 — workflow release-tag-on-main → reusable in this repo).
develop ──cut──► release/x.y.z ──deploy PROD──► validate ──PR──► main ──tag──► vX.Y.Z

Hotfix path

  1. Branch hotfix/TASK-{id}-{slug} from main.
  2. Cut / update patch release/x.y.z.
  3. Manual PROD deploy from that release ref.
  4. PR release → main → tag.
  5. Back-merge into develop so the fix is not lost.

Release checklist

  • PROD deploy completed from release/* with explicit confirm
  • Smoke / critical path validated
  • release/* merged to main
  • Tag vX.Y.Z on the merge commit
  • GitHub Release published (auto or manual)
  • Hotfixes back-merged to develop if any
Item Purpose
F.4 #58 workflow_dispatch deploy with prod/dev guards
F.5 #59 Auto tag + Release on release→main — shipped (release-tag-on-main-reusable.yml)
F.6 #60 ADR + merge-guard / branch-map updates — shipped (ADR-0007)