Skip to content

ADR 0009

github-actions[bot] edited this page Nov 21, 2026 · 1 revision

Status: accepted · Built: done · Date: 2026-11-21 · Supersedes: 0006

Partly supersedes ADR 0006: the website builds from release tags, not from pushes to main. Same process as Spotcraft (its ADR 0042) and spotkit.

One long-lived branch, main; a tag is a release

Context

Spotstrap has two long-lived branches. Work merges into dev; a release fast-forwards main to dev, tags it, and merges main back into dev. Spotcraft and spotkit, which Spotstrap is released next to, work on main alone. Two processes for three packages by one owner is one too many. ADR 0006 builds the website from pushes to main; with unreleased work on main, that would publish docs for changes that aren't released.

Decision

  • main is the only long-lived branch and the default branch. Work happens on short-lived branches cut from origin/main, named feature/<name>, bugfix/<name> or chore/<name> (lowercase letters, digits, dots, hyphens), and merges back through a pull request with a merge commit.
  • The branch-name check (its own workflow, so it re-runs when a pull request is retargeted) fails a pull request that doesn't target main or whose branch doesn't follow the names.
  • A release is a chore/release-X.Y.Z pull request, then a signed tag on its merge commit. CI publishes the tag to npm. Nothing is merged back.
  • The website builds from v* tags (and by hand), so spotstrap.dev shows the released version.

Consequences

  • One pull request per change and one per release; no fast-forward, no back-merge.
  • main holds unreleased work; npm and the website follow releases.
  • dev goes once main holds everything in it.

Clone this wiki locally