Skip to content

ADR-002: Release Branch Strategy

Date: 2026-03-14 Status: Accepted

Context

Need a branching and versioning strategy that supports: - Pre-release stages (alpha, beta, RC) - Ability to hotfix old releases while developing new features - Clean changelog aggregation per release - Not overkill for a solo/small team project

Options Considered

  1. GitHub Flow + Tags — single branch (master), releases are just tags
  2. Pro: dead simple

  3. Con: can't maintain multiple release lines simultaneously

  4. Release Branches — master as trunk, cut release/0.x branches for stabilization

  5. Pro: supports pre-release stages, hotfixes on old versions, clean cadence

  6. Con: slightly more process (cherry-picks between branches)

  7. Git Flow — master + develop + feature + release + hotfix branches

  8. Pro: very structured
  9. Con: overkill for 1-2 person project, lots of merge ceremony

Decision

Option 2: Release Branches.

  • master — development trunk
  • release/0.x — cut when starting a release cycle
  • Tags: v0.x.0-alpha.N -> v0.x.0-beta.N -> v0.x.0
  • Hotfixes cherry-picked to release branches

Rationale

  • Matches the desired alpha/beta/release cadence
  • Scales if contributors join, not overkill while solo
  • CI triggers on push to master and release/** branches
  • Release workflow triggers on v* tags, auto-detects pre-release from tag name
  • hatch-vcs derives version dynamically from git tags

Consequences

  • Must cherry-pick fixes between master and release branches
  • Must merge release branches back to master frequently (user preference)
  • Tags are immutable — can't change what a released version contains
  • Need discipline about what goes on release branches vs master