beads/RELEASING.md
Julian Knutsen b3ef65c854
release: prep v1.3.0 — version bump, changelog rollup, release process docs, formula fixes (#6038)
* chore: bump version to 1.3.0

Runs scripts/update-versions.sh 1.3.0, the sanctioned path per RELEASING.md.
Covers everything scripts/check-versions.sh gates: cmd/bd/version.go, the
three plugin manifests plus the marketplace, the MCP pyproject/__init__/
uv.lock pin, npm-package/package.json, the tracked .githooks managed-section
markers, default.nix and the Windows PE resource metadata.

scripts/check-versions.sh passes at 1.3.0.

* docs(changelog): roll up [1.3.0] for 2026-08-28

Creates the [1.3.0] section dated 2026-08-28 and leaves [Unreleased] empty
but present.

- Rolls up everything that was under [Unreleased].
- Adds a 'Breaking changes for v1.2.2 users' section. v1.2.2 shipped the
  v1.1.2 tree, so its users never received [1.2.1]; the five behavioral
  breaks documented there are restated (close policy on bd update -s, search
  including closed, the interactive-only last-touched fallback, bd human list
  status handling, dolt push/sync remote-adoption consent) with a pointer to
  the historical section rather than a copy of it. The two breaks new in
  1.3.0 (BEADS_DOLT_PORT precedence, actor '--' decoding) are indexed here
  and written up in full under Changed.
- Adds upgrade notes: first invocation auto-migrates v53 -> v66 (13
  migrations, 0054..0066, verified against the embedded migrations dir);
  per-step progress on stderr is TTY-gated, so CI sees nothing; back up
  first; the forward skew guard means co-resident older binaries refuse the
  store, so a shared-store fleet upgrades together; rollback via the recovery
  runbook's cursor-rollback procedure.
- Adds entries for eight changes that had no changelog line at all, each
  verified against the code on this branch: --profile -> --cpu-profile with
  no alias (#5126); the one-time content-derived aux-row id rekey, main 0061
  (#5150); events becoming clone-local, 0062 (#5162); the interactions.jsonl
  sidecar becoming opt-in behind audit.enabled (#4688); bd import erroring on
  redirected stdin with no source (#5171); auto-backup defaulting off under a
  sql-server (wy-zrmqr); bd hooks install --chain/--force becoming no-ops
  under marker sections (#5284); the new *.gate.lock workspace/physical-root
  gate files (#5046, #5093); and purge/prune tier selection (#5995).
- Moves the 'sort on listIssues' entry (#5666) out of [1.2.2] and into
  [1.3.0]. Its commit 8aaefe2d4 is not an ancestor of the v1.2.2 tag, so it
  never shipped in that release.

* feat(info): add the 1.3.0 versionChanges entry

RELEASING.md makes cmd/bd/info.go a required release step: versionChanges is
the channel 'bd info --whats-new' uses to tell an agent what changed under it.
The entry matches the existing format and carries the same upgrade notes as
CHANGELOG's [1.3.0] — the v53->v66 migration and its cost, the fleet
implication of the forward skew guard, the rollback pointer, the seven
behavioral breaks a v1.2.2 user meets, and the headline changes.

* docs(releasing): document the release-branch process, fix the semver wording, close the audited checklist gaps

Release-branch process (now in use for 1.3.0): a new 'Release Branches'
section covers cutting release/x.y.z from a SHA green on both Main and
Nightly Full Tests, landing every release-targeted change as a PR based on
the release branch and labeled status/needs-review-auto, tagging from the
branch, and forward-porting to main afterwards. Hotfixes are folded into the
same shape rather than a parallel one.

Semver: MAJOR is now removals and incompatible interface changes; documented
behavioral breaks that ship with migration notes are a MINOR bump, with the
obligation that makes that legitimate (CHANGELOG entry naming the override,
plus an info.go summary). 1.3.0 is cited as the worked example.

Checklist gaps the audit found: cross-compiling every goreleaser target
before tagging (GH#5662 — PR CI builds none of them, and the freebsd break
burned the v1.2.0 tag), the docs cutover (cli-docs.pin bump plus regen, and
the hand-maintained release line on docs/index.md, which had gone stale at
1.1.0), a release-notes rollup check for both an unemptied [Unreleased] and
entries misfiled under a previous tag, an explicit check-versions.sh gate,
and the info.go entry.

Also retires the bump-version.sh instructions: that script has been a
deprecation stub that exits 1 for some time, so the document's primary
version-bump instruction could not work. Replaced with update-versions.sh
plus check-versions.sh, and the file list corrected against what the script
touches now (uv.lock, the copilot plugin, the .githooks markers, winres) —
the old list named cmd/bd/templates/hooks/* and PLUGIN.md, neither of which
it writes. 'The Easy Way' now names the release molecule; release.sh is a
gateway that prints it.

Fixes the drifted table of contents while in the area.

* fix(release-formula): bump via update-versions.sh, verify via check-versions.sh

The formula carried its own hand-rolled copy of the version bump, and it had
drifted from the scripts it was copied from. bump-plugin-json pointed at
claude-plugin/.claude-plugin/plugin.json, a path that has not existed since
the plugins moved under plugins/beads/ — so the step would have failed
outright — and the copy covered none of the files added to the gate since:
the codex and copilot plugin manifests, integrations/beads-mcp/uv.lock, and
the BEADS INTEGRATION markers in .githooks/*. A release driven by this
formula would either die on the stale path or ship inconsistent versions,
which is how the v1.1.1 tag burned (stale uv.lock, discovered only in the
tag-triggered run) and how the v1.2.0 bump reddened main (stale hook
markers).

Replaces the seven hand-rolled bump steps with one that runs
scripts/update-versions.sh, which is the sanctioned path and cannot drift
from itself, and turns verify-versions into scripts/check-versions.sh — the
same gate the release-tag pre-push hook and CI run — instead of a grep list
that has to be maintained in parallel with the real one. Both steps carry the
two failure modes worth knowing about: uv missing (leaves uv.lock stale, fails
only after the tag exists) and the hook markers being rewritten wholesale
rather than matched.

Also renames push-main to reflect the release-branch process now documented
in RELEASING.md, and adds the forward-port reminder there.

Verified: each listed file checked against scripts/update-versions.sh and
scripts/check-versions.sh as they exist on this branch, and against a real
./scripts/update-versions.sh 1.3.0 run. go test ./scripts/ -run Release
passes (the formula still parses, and the cleanup-stale-dolt-orphans,
verify-homebrew-core and local-install assertions are untouched).

* docs: point the release banner at 1.3.0 and tell 1.2.2 users what this upgrade costs

The docs homepage carries a hand-maintained 'These docs are for the X.Y.Z
release' line that nothing generates or validates, so it had gone stale at
1.1.0 while the CLI docs pin had already moved to v1.2.2. It now names 1.3.0
and sends the reader to Upgrading first, since this upgrade crosses a schema
migration. RELEASING.md now carries a checklist item for it.

docs/getting-started/upgrading.md was entirely version-agnostic: strong on
mechanism (install methods, hooks, the remote-migrate gate, backup-first,
the multi-clone flow) and silent on which release you are coming from. A
1.2.2 user could read the whole page without learning that their database is
at v53 and that this step crosses 13 migrations. Adds an 'Upgrading to 1.3.0'
section covering the v53->v66 jump and why it is bigger than a routine one,
the slower first invocation and its TTY-gated per-step progress, the
forward-skew consequence for a shared store (upgrade every client together),
and the cursor-rollback runbook. It links to the backup and multi-clone
procedures already on the page rather than restating them.

Also adds the schema-version-mismatch runbook to the Recovery index table.
It was reachable only from the sidebar and the CHANGELOG, and the new
Upgrading section links to it.

Generated docs untouched: scripts/check-cli-docs-drift.sh passes against the
v1.2.2 pin, and the pin bump is a post-tag step (generate-cli-docs.sh builds
bd from the pinned tag, which does not exist until v1.3.0 is pushed).
go test ./test/docsync and scripts/check-doc-freshness.sh pass.

* fix(release-notes): correct the backup advice, the migration count, and the breaks undercount

Review round on #6038. Four findings, all of which made the upgrade notes
actively misleading rather than merely incomplete.

CRITICAL — bare 'bd backup' takes no backup. backupCmd is a runless cobra
parent (no Run/RunE, children init/sync/restore/remove/status, no default),
so cobra prints usage and exits 0 without writing anything. A user following
'bd backup' before an irreversible 27-migration upgrade sees help text and
proceeds believing a snapshot exists; in a script, 'bd backup && ...' proceeds
on exit 0. Replaced with 'bd backup init <path>' then 'bd backup sync' in
CHANGELOG, info.go and upgrading.md, and said in each place that bare
'bd backup' takes no backup.

Also CRITICAL, same class: the backup had no ordering rule. Under 1.3.0
'bd export' triggers autoMigrateOnVersionBump before it exports, so a backup
taken after installing is a post-migration snapshot that cannot protect
against the migration going wrong. All three copies now say to back up with
the OLD binary before installing, and carry the neighbouring rule that
remote-backed stores must finish 'bd dolt push' first, since the
pending-migration gate refuses push/pull too.

Migration count: '13' was the main series only. schema.go runs the main
source then the ignored source through the same 'Applying migration %04d'
printer, and the ignored series moves 0011 -> 0025 here, so the run is ~27
migrations and the counter visibly restarts from 0066 back to 0012. That
backwards jump is exactly the signature an operator reads as a loop and
kills — while these same notes say 'do not interrupt it'. All three copies
now state ~27, show the restart in sample output with real migration names,
and label it as not a restart.

Breaks undercount: 'seven' read as an enumeration, but [1.2.1] carries three
more entries explicitly labelled BREAKING that a v1.2.2 user also meets.
Retitled as highlights with an explicit pointer to the full [1.2.1] section,
and added the three: '--readonly serve' now refused (load-bearing next to the
'restart any long-running bd serve' advice — it will not come back up), the
config kv-plane drop, and the backend package's orphan-handling removal. The
info.go entry gets the same pointer and the same three, since 'bd info' is the
only copy reachable after installing.

Upgrade-time reader is now pointed at 'bd upgrade review', which computes the
delta since the previously-run version via getVersionsSince, instead of
'bd info --whats-new', whose showWhatsNew loops the entire versionChanges
array with no cap (~80 entries) to deliver the ~11 relevant bullets.

* fix(check-versions): gate the copilot manifest and the winres files, stop overclaiming

Three review findings, all cases where the gate said more than it checked.

Copilot manifest was bumped but never gated. update-versions.sh:101 rewrites
plugins/beads/.copilot-plugin/plugin.json with a sed anchored on the OLD
version, and check-versions.sh never read the file — the string 'copilot' did
not appear in it. That is the same drift class that carried stale .githooks
markers through v1.2.0: once the file drifts the bump silently no-ops on it,
the green line prints, the pre-push hook and CI pass, and the Copilot plugin
ships advertising the previous version. Now gated. Verified it fails: drifting
the file to 1.2.2 reddens the run and exits 1.

winres was verified by nothing after the formula rewrite deleted the steps
that grepped it. Restored as real gates rather than formula prose, since
manifest.xml's <assemblyIdentity> version has no backstop at all —
gen-winres.sh re-derives winres.json's numeric fields from version.go at build
time, but the manifest's version is embedded verbatim, and update-versions.sh
rewrites it with a sed anchored on the old base version. Prerelease-correct:
file_version/product_version and the manifest's four-part version are checked
against the BASE version while FileVersion/ProductVersion are checked against
the full string, which is what update-versions.sh writes. The manifest grep is
anchored at line start because the XML declaration also carries a version=
attribute. Verified it fails on drift.

The success line claimed a 'released-docs policy pass' for a check that no
longer exists — the script reads no docs file — while this same release adds
a MANUAL docs-cutover checklist item precisely because nothing automated
covers docs. An operator reading that line would reasonably skip the manual
checks. Now says version files only, and names the manual steps. The two
vestigial echoes left behind by the deleted check are gone.

The failure remedy was also wrong, and wrong in the direction that loops the
operator: it said to re-run update-versions.sh, which derives CURRENT_VERSION
from cmd/bd/version.go (line 70) and substitutes old->new literally. After the
first bump version.go already holds the new version, so a re-run rewrites
new->new and no-ops on exactly the drifted file the gate just named. Verified
empirically — with the copilot manifest and manifest.xml drifted to 1.2.2,
'update-versions.sh 1.3.0' prints 'Bumping: 1.3.0 → 1.3.0' and leaves both at
1.2.2. Only the githooks markers (wholesale regex) and uv.lock (uv lock) heal
on a re-run, and the message now says so and gives the three remedies that
actually work.

shellcheck clean.

* docs(releasing): make the release-branch policy internally consistent

The policy landed in the previous commit but three procedures in the same
files still contradicted it, and the formula implemented the wrong one.

RELEASING.md said 'Nothing is pushed straight to the release branch' and then,
150 lines down, direct-pushed the release branch and minted the tag before the
merge. Two concrete failures: with branch protection the push is rejected
after the tag already exists locally, and with a squash merge the tag points
at a commit that is not an ancestor of release/x.y.z — goreleaser packages
CHANGELOG.md FROM THE TAG into every published archive, so the release ships
the pre-review notes. Both the CHANGELOG-commit block and the bump block now
open a PR, and tagging is a separate step against the merged commit. The
literal 'git push origin main' under the substitution blockquote is gone, as
is the direct push in the docs-pin block.

The formula implemented the wrong order too: commit-release -> create-tag ->
push-main. Reordered to commit-release -> push-main (land the PR) -> create-tag
(on the merged commit) -> push-tag, and create-tag now states why the order
matters.

preflight-pull was untouched by the last commit and still hard-coded main:
divergence recovery was 'git reset --hard origin/main'. Running the molecule on
a release branch and following that destroys the reviewed release-prep commit
and leaves the operator tagging an untested main SHA — precisely the failure
the policy exists to prevent. It now pins the release branch into a variable
first and resets to that; the backup branch moved to Option 1 rather than
Option 3.

'git push origin release/{{version}}' broke every prerelease run: the branch
convention is release/x.y.z, so an RC rendered release/1.3.0-rc.1 and failed
with 'src refspec does not match any', and the forward-port 'git log
main..release/{{version}}' then died on an unknown revision. Now derives the
base version and says why.

The RC workflow still cut tags from the tip of main, which is what the new
policy calls 'a SHA nobody has fully tested' — and worse, an RC exists to
validate the SHA the stable release ships, while the stable tag now comes off
the release branch, so it validated a different SHA by construction. RCs are
now cut on the base version's release branch, and promotion stays on it.

Accuracy fixes in the same pass: verify-versions no longer claims the (now
corrected) 'released-docs policy' string or tells the operator to re-run the
bump — a no-op after the first run, proven in the previous commit — and no
longer prints a prerelease-broken 'grep -c {{version}} winres.json # 4', which
yields 2 for an RC because the numeric PE fields carry the base version. It
now points at check-versions.sh, which gates winres correctly. The 'three
plugin manifests' and 'compares everything else against it' claims are
corrected to match what the script actually reads, and RELEASING.md names
default.nix and README.md as bumped-but-ungated.

go test ./scripts/ and ./test/docsync/ pass; formula still parses and the DAG
is acyclic.

* ci: run PR workflows on release/** branches

Release-targeted PRs currently run almost no CI. pr.yml, pr-risk.yml,
conformance.yml, regression.yml and cross-version-smoke.yml all declare
'pull_request: branches: [ main ]', and every push trigger in the repo is
'branches: [main]' or 'tags: v*'. So a push to release/1.3.0 fires zero
workflows, and a PR based on it gets only the three workflows with no branch
filter (migration-test, nix-build on its paths, docs-mintlify).

That puts the new release-branch policy on a contradiction: it routes the
version bump and 'any fix the release validation turns up' onto a branch where
they land with no unit, lint, conformance or regression coverage, and the
first full signal is the tag build — where a failure burns the tag by this
document's own rule. The policy was written to stop tagging untested SHAs and
was quietly producing them.

Adds release/** to the pull_request branch filter of those five. Push triggers
are deliberately left alone: release branches take changes through PRs, so the
pull_request event is the one that matters, and widening push would double
every run on merge.

cross-version-smoke is the highest-value of the five here — a release-targeted
PR is exactly where cross-version upgrade breakage is most expensive to find
at tag time.

This PR is the vehicle because it targets release/1.3.0, so the new filters
take effect for its own subsequent pushes.

All five files parse; go test ./scripts/ (which includes the workflow lint
tests) passes.

* docs: reconcile the 1.3.0 upgrade notes with the merged release set

Merging origin/release/1.3.0 changed three facts the upgrade notes assert.

Migration count. The merge added ignored/0026_dep_rekey_dedup_marker (#6045),
so the clone-local series now runs 0012 -> 0026, not 0012 -> 0025. Recounted
from the tree: 13 main-series (0054..0066, unchanged) + 15 clone-local = ~28,
not ~27. Corrected in CHANGELOG, cmd/bd/info.go and upgrading.md, including
the trailing line count in the 'counter restarts' explanation.

Shared servers. #6048 (#5920, #5043) means a shared dolt sql-server is no
longer auto-migrated at all — it waits for explicit consent via
'bd migrate schema'. The notes said flatly that 'the first invocation migrates
your schema in place', which is now true only for embedded/local stores and
would have sent a shared-server operator looking for a migration that never
runs. All three copies now scope that claim and point at the new 'Shared
servers' section upgrading.md gained in the same merge. Verified
'bd migrate schema' exists (cmd/bd/migrate.go:848) and that --global is a root
persistent flag (main.go:818), so the cited invocations are real.

#5896. The auto-export entry said #5896 'stays open for embedded mode, where
bd delete still wedges auto-export'. #6059 closed exactly that. Reworded to
point at the store-history heal rather than claiming a live bug.

check-versions.sh 25/25 green, go build ./... clean, go test ./scripts/... and
./test/docsync/ pass, check-cli-docs-drift and check-doc-freshness pass.

* docs(changelog): fold in the proposed changelog lines from the merged 1.3.0 set

Adds the 'proposed changelog' text carried in the bodies of the PRs that
merged into release/1.3.0 after this rollup was first written. Text is the
authors' own; where a body gave it in conventional-commit form rather than as
a bullet, the sentence is preserved and only the 'fix(scope):' prefix dropped
and a bold lead added to match the section.

Changed: #6048 (two bullets — shared-store consent, and the smart gate's
first-mover/fast-forward arms going embedded-only), #6036 (exported packages
marked EXPERIMENTAL), #6053's revision-token bullet, #6049 (migration-test and
upgrade-smoke wisp-plane coverage).

Fixed: #6040 (server-mode lost updates), #6044 (removed-backend rejection),
#6045 (convergent dependency rekey), #6046 (tracked ignored_schema_migrations
heal), #6054 (ignored-cursor floor clamp), #6059 (delete-wedge heal), #6057
(full GC after flatten/compact), #6060 (--storage-class routes), #6061
(journal actor attribution), #6062 (proxied/gateway init errors), and #6053's
two typed-JSON bullets.

Security: new subsection for #6047 (Go 1.26.7 toolchain bump closing seven
reachable stdlib advisories, plus the dependency bumps clearing all 25).
Placed after Fixed per Keep a Changelog ordering.

Documentation: #6052's multi-rig/proxied gate limitation. Its body calls it a
release-notes line rather than a changelog line, so it may want moving.

Contributor credit carried where the PR body gives it: #6040 keeps its
'Reported and fixed by @nova-submodules' sentence, and #6044 gains a note that
its detection helper is ported from @steveyegge's #4740. NOTE: #5064 (aux
row-key encoding drift) carries credit to @marcodelpin in its body but no
proposed changelog line, so it has no entry here — flagging rather than
inventing one.

#6043 was a REPLACEMENT, not an addition: it asked for the existing
MIGRATION-FREEZE bullet to be swapped for vendor-neutral text. Done — the old
bullet named the gt CLI, 'town root' and 'gt migrate thaw'; the new one
describes the generic marker discovery, exit code 14, and the wider set of
maintenance that stands down.

#6055 and #6056 were still OPEN at the time of writing. Their four proposed
lines are included but fenced in a PROVISIONAL HTML comment block that says to
delete it before tagging if either PR does not land.

check-versions.sh 25/25, go build clean, go test ./scripts/... and
./test/docsync/ pass, check-cli-docs-drift and check-doc-freshness pass.

* docs(changelog): credit the three carried contributor fixes

Adds the entries for the merged PRs that carried contributor work but shipped
no proposed changelog line of their own, in the maintainer's supplied wording,
expanded to the surrounding entries' voice.

ATTRIBUTION CORRECTED on #5064. The supplied wording read 'Reported by
@marcodelpin, fixed by @maphew'; the PR body says the opposite. Its '## Credit'
section: 'The fix is @marcodelpin's, from 767d5dcd on their fork... The
diagnosis behind it — the chunk-level characterisation, the negative result on
the minimised fixture, the dolt 2.1.10 re-test, the recover-rows verification —
is theirs too... isSchemaEncodingDriftErr and its table-driven test come from
that commit.' @maphew (the PR author) absorbed it with a review-requested
semantic rework. Written as 'Diagnosis and fix by @marcodelpin, carried and
reworked by @maphew' so the contributor is not demoted to reporter of a bug
they also fixed.

Scope corrected on the same entry. The supplied wording reads as new behavior,
but git grep against the v1.1.2 tag finds both isSchemaEncodingDriftErr and
aux_row_rekey_drifted already present in internal/storage/schema/
aux_row_id_backfill.go — v1.2.2 is the v1.1.2 tree, so v1.2.2 users already
have this fix, and it is already documented under [1.1.2]. #5064 carries it
onto the main line. The entry says so, so a v1.2.2 reader does not conclude
they were exposed and go looking for a migration that does not concern them.

#5783 and #6037 verified against their PR bodies before writing; both supplied
claims hold. #5783: Config.LenientOpen reached server mode but newServerMode
never read it and the field's doc comment said 'Ignored in server mode', so the
dirty-table refusal's own recovery command could not run — and server mode has
no 'move the directory aside and re-bootstrap' alternative. #6037: bd init
persists a git-origin-derived sync.remote into the tracked config by design,
bootstrap rejected exactly that shape before the origin auto-detect, and
Action=='none' conflated 'already exists' with 'refused', printing a success
tick and exiting 0 having created nothing.

Also notes in the PROVISIONAL fence that the RC is gated on #6055/#6056
merging, so the fence comes off at RC-prep time rather than being an open
question.

check-versions.sh 25/25, go test ./test/docsync/ passes.

* fix(release): create release-prep branch before pushing it

The new release-branch/prep-PR flow pushed `release-prep/v<version>`
without ever creating that branch, so `push-main` (and the RELEASING.md
runbook) failed on first run with
`error: src refspec release-prep/v<version> does not match any`.

Add `git checkout -b` before each prep-branch push — the formula
`push-main` step and both RELEASING.md landing snippets — so the branch
exists before it is pushed, mirroring the existing `REL_BRANCH` guard in
the same step.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-08-30 22:19:35 -07:00

31 KiB

Release Process for Beads

This document describes the complete release process for beads, including GitHub releases, Homebrew, PyPI (MCP server), and npm packages.

Table of Contents

Overview

A beads release involves multiple distribution channels:

  1. GitHub Release - Binary downloads for all platforms
  2. Homebrew - macOS/Linux package manager
  3. PyPI - Python MCP server (beads-mcp)
  4. npm - Node.js package for Claude Code for Web (@beads/bd)

For routine releases, run the release molecule:

bd mol wisp beads-release --var version=1.3.0

.beads/formulas/beads-release.formula.toml defines the whole flow as resumable steps with a CI gate: preflight → CHANGELOG/info.go → version bump → commit/tag/push → gate on release.yml → verify GitHub/npm/PyPI/Homebrew → local install. ./scripts/release.sh 1.3.0 is a thin gateway that prints this command; it does not run a release itself.

The rest of this document is the manual / step-by-step process, useful for understanding what the molecule does and for handling edge cases (hotfixes, rollbacks, manual PyPI/npm publishes).

Prerequisites

Required Tools

  • git with push access to gastownhall/beads
  • goreleaser for building binaries
  • npm with authentication (for npm releases)
  • python3 and twine (for PyPI releases)
  • gh CLI (GitHub CLI, optional but recommended)

Required Access

  • GitHub: Write access to repository and ability to create releases
  • GitHub: Ability to create protected v* release tags. The repository should restrict refs/tags/v* creation, updates, and deletion to trusted release maintainers.
  • PyPI: Maintainer access to beads-mcp package
  • npm: Member of @beads organization

Verify Setup

# Check git
git remote -v  # Should show gastownhall/beads

# Check goreleaser
goreleaser --version

# Check GitHub CLI (optional)
gh auth status

# Check npm
npm whoami  # Should show your npm username

# Check Python/twine (for MCP releases)
python3 --version
twine --version

Release Branches

Releases are cut from a release/x.y.z branch, not from whatever main happens to be when the tag is pushed. main moves continuously and the release-critical gates do not all run on every PR, so "tag the tip of main" means tagging a SHA nobody has fully tested. A burned tag is never reused (the v1.1.1 and v1.2.0 precedents), so that gamble is expensive.

Cut the branch from a SHA that is green on both Main and Nightly Full Tests. The Main workflow runs on push to main and the Nightly Full Tests workflow runs on a 2am UTC schedule, so the newest SHA with both is usually a few hours behind the tip:

gh run list --workflow Main --branch main --status success --limit 5 \
  --json headSha,conclusion,createdAt
gh run list --workflow "Nightly Full Tests" --status success --limit 3 \
  --json headSha,conclusion,createdAt

git fetch origin
git branch release/1.3.0 <the-green-sha>
git push origin release/1.3.0

Everything targeted at the release lands on the release branch as a PR. Base the PR on release/x.y.z, not main, and label it status/needs-review-auto so it goes through the automated review workflow like any other change. That includes the release-prep PR itself (version bump, CHANGELOG, cmd/bd/info.go) and any fix the release validation turns up. Nothing is pushed straight to the release branch.

Tag from the release branch, following 1. Prepare Release onward with the branch checked out in place of main.

Forward-port to main after the release ships. Every commit that landed only on the release branch — the version bump included — needs a PR back to main, or the next release silently drops it and the version files disagree with the newest tag. Do this as one PR immediately after the tag is pushed, while the set of release-only commits is still obvious:

git log --oneline main..release/1.3.0

(See PR #5782 for the shape of a forward-port PR.)

Release Checklist

Before starting a release:

  • release/x.y.z branch cut from a SHA green on Main and Nightly Full Tests (see Release Branches)
  • All tests passing (go test ./...)
  • npm package tests passing (cd npm-package && npm run test:all)
  • Upgrade smoke tests pass (make test-upgrade) — see Release Stability Gate
  • Regression tests pass (make test-regression)
  • Every release target cross-compiles — see Cross-compile before tagging. PR CI does not build them (#5662), and a target that fails at tag time burns the tag.
  • CHANGELOG.md updated with release notes (see format below)
  • CHANGELOG rollup checked — nothing left under [Unreleased] that belongs in this release, and nothing filed under a previous release's section that shipped after that tag. Verify with git merge-base --is-ancestor <commit> <previous-tag> when in doubt.
  • cmd/bd/info.go versionChanges entry added for this version
  • Breaking changes documented with migration steps and recovery instructions
  • Docs cutover planned — docs/cli-docs.pin bump plus ./scripts/generate-cli-docs.sh, and the release line on the docs homepage (docs/index.md). See Documentation Site (Mintlify).
  • ./scripts/check-versions.sh passes
  • No uncommitted changes
  • On the release/x.y.z branch and up to date with origin

Cross-compile before tagging

.goreleaser.yml builds darwin, linux, windows and freebsd, but PR CI builds none of the cross targets — the v1.2.0 tag burned on a freebsd compilation failure that no pre-tag gate could have caught (#5661 fixed the break, #5662 tracks the CI gap). Until that gap is closed, build them by hand before tagging:

goreleaser build --snapshot --clean

A failure here costs a rebase. The same failure after the tag is pushed costs the tag.

1. Prepare Release

The snippets below say main where they mean "the branch you are releasing from". Since Release Branches, that is release/x.y.z: substitute it for main in every git push and git checkout here, and land the changes as a PR against the release branch rather than pushing directly.

Update CHANGELOG.md

IMPORTANT: Do this FIRST before running bump-version script.

Add release notes to CHANGELOG.md:

## [0.22.0] - 2025-11-04

### Added
- New feature X
- New command Y

### Changed
- Improved performance of Z

### Fixed
- Bug in component A

### Breaking Changes
- Changed behavior of B (migration guide)

Commit the CHANGELOG changes and open a PR against the release branch:

git add CHANGELOG.md
git commit -m "docs: Add CHANGELOG entry for v0.22.0"
git checkout -b release-prep/v0.22.0
git push -u origin release-prep/v0.22.0
gh pr create --base release/0.22.0 --label status/needs-review-auto

Update Version and Create Release Tag

./scripts/update-versions.sh rewrites every version reference in one pass. It does no git operations — commit, tag and push are yours. (bump-version.sh is retired; it now only prints a pointer here.)

./scripts/update-versions.sh 0.22.0
./scripts/check-versions.sh          # must pass before you commit

This updates:

  • cmd/bd/version.go — CLI version constant. This is the canonical version: check-versions.sh reads it and compares the gated files against it. Note that "gated" is narrower than "updated" — default.nix and README.md are bumped here but checked by nothing, so eyeball them.
  • integrations/beads-mcp/pyproject.toml — MCP server version
  • integrations/beads-mcp/src/beads_mcp/__init__.py — MCP Python version
  • integrations/beads-mcp/uv.lock — the beads-mcp pin, via uv lock. A stale lock fails the release workflow's MCP gate after the tag exists and can no longer be rewritten; that burned the v1.1.1 tag. Install uv before bumping, or the script warns and skips it.
  • plugins/beads/.claude-plugin/plugin.json — Claude plugin version
  • plugins/beads/.codex-plugin/plugin.json — Codex plugin version
  • plugins/beads/.copilot-plugin/plugin.json — Copilot plugin version
  • .claude-plugin/marketplace.json — Claude marketplace version
  • npm-package/package.json — npm package version
  • .githooks/* — the BEGIN/END BEADS INTEGRATION v<version> markers on the tracked managed hook sections, held byte-equal to the cmd/bd/hooks.go generator by TestTrackedManagedHookSectionsMatchGenerator. Skipping them reddens the branch only after the push (that was the v1.2.0 bump).
  • default.nix — Nix package version
  • cmd/bd/winres/winres.json, cmd/bd/winres/manifest.xml — Windows PE resource metadata (the numeric fields take the base version, with any prerelease suffix stripped)
  • README.md — the static Alpha version badge, if one is present

It does not touch CHANGELOG.md, cmd/bd/info.go, or default.nix's vendorHash. Write the release notes first (above), and run ./scripts/update-nix-vendorhash.sh if go.mod/go.sum changed since the last tag.

Then commit and land it as a PR — not a direct push, and do not tag yet:

git add -A
git commit -m "chore: bump version to 0.22.0"
git checkout -b release-prep/v0.22.0
git push -u origin release-prep/v0.22.0
gh pr create --base release/0.22.0 --label status/needs-review-auto

Tag only after that PR merges, and tag the merged commit:

git checkout release/0.22.0 && git pull
git tag -a v0.22.0 -m "Release v0.22.0"
git push origin v0.22.0

Two reasons the order matters, both of which have teeth. With branch protection on, a direct push to the release branch is rejected — after you have already minted the tag locally. And with a squash merge, a tag created before the merge points at a commit that is not an ancestor of release/x.y.z; goreleaser packages CHANGELOG.md from the tag into every published archive, so the release would ship the pre-review notes.

Pushing the tag triggers GitHub Actions to build release artifacts automatically.

The tag workflow re-runs release-critical package gates before publishing:

  • make ci-package-mcp builds and validates the MCP package, then the PyPI job publishes the validated dist/* artifact from that gate.
  • make ci-package-npm validates the npm wrapper package before npm publish. publishes GitHub release assets.

The npm publish job also waits for the macOS release assets, because the npm postinstall script downloads platform-specific archives from the GitHub release.

Recommended workflow:

# 1. Update CHANGELOG.md and cmd/bd/info.go with release notes (manual step)

# 2. Bump versions and verify
./scripts/update-versions.sh 0.22.0
./scripts/check-versions.sh

# 3. Land it on the release branch as a PR (label status/needs-review-auto)

# 4. Test locally, then tag the merged commit and push
git tag -a v0.22.0 -m "Release v0.22.0"
git push origin v0.22.0

The release workflow is intentionally gated to refs/tags/v*. A manual workflow dispatch from a branch will skip publishing jobs; manual reruns must select the release tag.

2. GitHub Release

GoReleaser automates binary building and GitHub release creation:

# Clean any previous builds
rm -rf dist/

# Create release (requires GITHUB_TOKEN)
export GITHUB_TOKEN="your-github-token"
goreleaser release --clean

# Or use gh CLI for token
gh auth token | goreleaser release --clean

This will:

  • Build binaries for all platforms (macOS, Linux, Windows - amd64/arm64)
  • Create checksums
  • Generate release notes from CHANGELOG.md
  • Upload everything to GitHub releases
  • Mark as latest release

Manual Release (Alternative)

If goreleaser doesn't work:

# Build for all platforms
./scripts/build-all-platforms.sh

# Create GitHub release
gh release create v0.22.0 \
  --title "v0.22.0" \
  --notes-file CHANGELOG.md \
  dist/*.tar.gz \
  dist/*.zip \
  dist/checksums.txt

Verify GitHub Release

  1. Visit https://github.com/gastownhall/beads/releases
  2. Verify v0.22.0 is marked as "Latest"
  3. Check all platform binaries are present:
    • beads_0.22.0_darwin_amd64.tar.gz
    • beads_0.22.0_darwin_arm64.tar.gz
    • beads_0.22.0_linux_amd64.tar.gz
    • beads_0.22.0_linux_arm64.tar.gz
    • beads_0.22.0_windows_amd64.zip
    • checksums.txt

3. Homebrew Update

Homebrew uses the beads formula in homebrew-core. Do not publish or revive the old bd formula in gastownhall/homebrew-beads; having two independently updated Homebrew formulas causes version drift and installs the wrong binary for some users.

Updates to the supported Homebrew formula are handled through Homebrew core after GitHub Release artifacts are available.

Verify Homebrew

After the GitHub Release is published, verify the Homebrew package:

# Update Homebrew
brew update

# Install/upgrade
brew upgrade beads  # or: brew install beads

# Verify
bd version  # Should show 0.22.0

4. PyPI Release (MCP Server)

The MCP server is a Python package published separately to PyPI.

Prerequisites

# Install build tools
pip install build twine

# Verify PyPI credentials
cat ~/.pypirc  # Should have token or credentials

Build and Publish

# Navigate to MCP server directory
cd integrations/mcp/server

# Verify version was updated
cat pyproject.toml | grep version

# Clean old builds
rm -rf dist/ build/ *.egg-info

# Build package
python -m build

# Verify contents
tar -tzf dist/beads-mcp-0.22.0.tar.gz

# Upload to PyPI (test first)
twine upload --repository testpypi dist/*

# Verify on test PyPI
pip install --index-url https://test.pypi.org/simple/ beads-mcp==0.22.0

# Upload to production PyPI
twine upload dist/*

Verify PyPI Release

# Check package page
open https://pypi.org/project/beads-mcp/

# Install and test
pip install beads-mcp==0.22.0
python -m beads_mcp --version

5. Plugin Marketplace Update

Update the plugin marketplace metadata files:

# Update .claude-plugin/marketplace.json
# Change version to match current release
vim .claude-plugin/marketplace.json

# Update plugins/beads/.claude-plugin/plugin.json if needed
vim plugins/beads/.claude-plugin/plugin.json

# Update plugins/beads/.codex-plugin/plugin.json if needed
vim plugins/beads/.codex-plugin/plugin.json

# Commit changes
git add .claude-plugin/ plugins/beads/.claude-plugin/ plugins/beads/.codex-plugin/
git commit -m "chore: Update plugin marketplaces to v0.22.0"

Note: These files define how beads appears in Claude Code and Codex plugin marketplaces. Version should match the release version.

Documentation Site (Mintlify)

The published docs are the Mintlify site rooted at docs/, deployed from main via the Mintlify GitHub integration — no release-time docs snapshot is needed. The site documents the current release line only (see engdocs/decisions/2026-07-10-mintlify-docs-overhaul.md). Day to day, the generated CLI reference is kept fresh by scripts/generate-cli-docs.sh and its PR drift gate, not by the release process.

But the release pin IS a release-time step. docs/cli-docs.pin names the release tag the docs corpus is generated from and validated against (engdocs/decisions/2026-07-17-docs-release-pin.md); it lags main between releases by design, so any command or flag added on main since the last bump is invisible to scripts/check-doc-flags.sh Check 4 ("covers all live top-level CLI commands" passes vacuously for it, e.g. wy-gx5rj for bd sync). Bump it as part of THIS release, not a follow-up:

# After tagging (see "Update Version and Create Release Tag" above).
# generate-cli-docs.sh builds bd from the pinned tag, so the tag must exist.
echo "v0.22.0" > docs/cli-docs.pin
./scripts/generate-cli-docs.sh
git add docs/cli-docs.pin docs/CLI_REFERENCE.md docs/cli-reference docs/docs.json
git commit -m "docs: bump CLI docs pin to v0.22.0"

The pin bump lands on main, since that is where Mintlify deploys from — fold it into the forward-port PR described in Release Branches rather than pushing it to the release branch (or to main) directly.

Skipping this step doesn't fail fast — Check 4 stays green (it validates against the old pin) until the next bump, at which point every command added across the skipped releases shows up at once as a pile of "missing from docs/CLI_REFERENCE.md" failures with no obvious release to blame.

The docs homepage names the release line, and it is hand-maintained. docs/index.md carries a line of the form "These docs are for the X.Y.Z release of beads" with a link to that tag's release notes. Nothing generates or validates it, so it goes stale silently — it still said 1.1.0 when the pin had already moved to v1.2.2. Update it in the same commit as the pin:

rg 'These docs are for the' docs/index.md

6. npm Package Release

The npm package wraps the native binary for Node.js environments.

Prerequisites

# Verify npm authentication
npm whoami  # Should show your username

# Verify you're in @beads org
npm org ls beads

Update and Test

# Navigate to npm package
cd npm-package

# Version should already be updated by update-versions.sh
cat package.json | grep version

# Run all tests
npm run test:all

# Should see:
# ✅ All unit tests passed
# ✅ All integration tests passed

Test Installation Locally

# Pack the package
npm pack

# Install globally from tarball
npm install -g ./beads-bd-0.22.0.tgz

# Verify binary downloads correctly
bd version  # Should show 0.22.0

# Test in a project
mkdir /tmp/test-npm-bd
cd /tmp/test-npm-bd
git init
bd init
bd create "Test issue" -p 1
bd list

# Cleanup
npm uninstall -g @beads/bd
rm -rf /tmp/test-npm-bd
cd -
rm beads-bd-0.22.0.tgz

Publish to npm

# IMPORTANT: Ensure GitHub release with binaries is live first!
# The postinstall script downloads from GitHub releases

# Publish to npm (first time use --access public)
npm publish --access public

# Or for subsequent releases
npm publish

Verify npm Release

# Check package page
open https://www.npmjs.com/package/@beads/bd

# Install and test
npm install -g @beads/bd
bd version  # Should show 0.22.0

# Test postinstall downloaded correct binary
which bd
bd --help

7. Verify Release

After all distribution channels are updated, verify each one:

GitHub

# Download and test binary
wget https://github.com/gastownhall/beads/releases/download/v0.22.0/beads_0.22.0_darwin_arm64.tar.gz
tar -xzf beads_0.22.0_darwin_arm64.tar.gz
./bd version

Homebrew

brew update
brew upgrade beads
bd version

PyPI

pip install --upgrade beads-mcp
python -m beads_mcp --version

npm

npm install -g @beads/bd
bd version

Installation Script

# Test quick install script
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
bd version

Docs Cutover

cat docs/cli-docs.pin                      # the tag just released, not an older one
rg 'These docs are for the' docs/index.md  # the version just released

If either is stale, do the bump from the Documentation Site (Mintlify) step above before calling the release done.

Release Notes Rollup

# [Unreleased] should be empty, and the newest dated section is this release
rg -n '^## \[' CHANGELOG.md | head -3

Also confirm nothing shipped after the previous tag is still filed under that tag's section — the v1.2.2 section carried an entry for a commit that was never in v1.2.2, which is invisible until someone reads the release notes and looks for a feature their binary does not have:

git merge-base --is-ancestor <commit> <previous-tag> && echo "in the tag" || echo "MISFILED"

Prerelease / Release Candidate (RC) Workflow

Release candidates let a build be validated through the full release pipeline without promoting it to the stable channels. An RC carries a SemVer prerelease identifier (e.g. 1.1.0-rc.1); Python tooling normalizes this to PEP 440 form (1.1.0rc1).

How a prerelease tag differs from a stable release:

  • GitHub release is published and marked as a prerelease (goreleaser release.prerelease: auto), with binaries for all platforms.
  • Homebrew is not updated (goreleaser brews.skip_upload: true; the core formula only tracks stable releases).
  • PyPI and npm publish jobs are skipped. The publish-pypi and publish-npm jobs are gated with !contains(github.ref_name, '-'), so a tag containing a - never reaches the stable package channels.
  • Docs are unaffected. The docs site publishes from main via the Mintlify GitHub integration; there is no release-time docs snapshot for either prereleases or stable releases.

Cut an RC

An RC is cut from the release branch, like everything else. This is the point of an RC: it validates the SHA the stable release will ship. Tagging the tip of main instead validates a different SHA by construction — the stable tag comes off release/x.y.z — and re-introduces the "tag a SHA nobody has fully tested" failure that Release Branches exists to prevent. Note the branch is named for the base version: an RC for 1.1.0 is cut on release/1.1.0, not release/1.1.0-rc.1.

# 0. Cut (or check out) the release branch — see Release Branches above.
git checkout release/1.1.0

# 1. Update CHANGELOG.md and cmd/bd/info.go with the RC notes (manual step),
#    same as a stable release. Date the CHANGELOG section.

# 2. Bump versions. update-versions.sh accepts a prerelease identifier, and
#    also refreshes uv.lock (PEP 440 normalizes 1.1.0-rc.1 to 1.1.0rc1).
./scripts/update-versions.sh 1.1.0-rc.1
#    Windows PE numeric fields (winres file_version/product_version and the
#    manifest <assemblyIdentity> version) are set to the base version 1.1.0,
#    because PE versions must be purely numeric; gen-winres.sh strips the
#    prerelease suffix the same way at build time, and check-versions.sh
#    checks those fields against the base version for exactly this reason.

# 3. Validate locally.
./scripts/check-versions.sh

# 4. Open a PR for the RC prep against release/1.1.0 and have it reviewed.
#    RC prep should land through normal review, not auto-merge.

After the RC prep merges, cut the tag from the merged commit on the release branch:

git checkout release/1.1.0 && git pull
git tag -a v1.1.0-rc.1 -m "Release candidate v1.1.0-rc.1"
git push origin v1.1.0-rc.1

Pushing the v* tag triggers the release workflow with the prerelease behavior above. Tag creation is restricted to release maintainers; see Prerequisites.

Validate and promote

  • Install the RC from the GitHub prerelease assets and exercise the changes it is gating before promoting.
  • To promote to stable, bump to the base version with no suffix (./scripts/update-versions.sh 1.1.0) on the same release branch, so the stable tag lands on the SHA the RC validated. The stable release does publish to Homebrew/PyPI/npm, so follow the standard Prepare Release steps from there.

Hotfix Releases

For urgent bug fixes:

A hotfix is a release branch cut from the tag instead of from a green main SHA; everything else — PRs against the branch, the forward-port afterwards — is the same as Release Branches.

# Create the release branch from the tag being fixed
git checkout -b release/0.22.1 v0.22.0
git push origin release/0.22.1

# Land the fix as a PR against release/0.22.1, then bump
./scripts/update-versions.sh 0.22.1
./scripts/check-versions.sh
git commit -am "chore: bump version to 0.22.1"

# Tag and release
git tag -a v0.22.1 -m "Hotfix release v0.22.1"
git push origin release/0.22.1
git push origin v0.22.1

# Forward-port the fix AND the version bump to main
git log --oneline main..release/0.22.1

Rollback Procedure

If a release has critical issues:

1. Mark GitHub Release as Pre-release

gh release edit v0.22.0 --prerelease

2. Create Hotfix Release

Follow hotfix procedure above to release 0.22.1.

3. Deprecate npm Package (If Needed)

npm deprecate @beads/bd@0.22.0 "Critical bug, please upgrade to 0.22.1"

4. Yank PyPI Release (If Needed)

# Can't delete, but can yank (hide from pip install)
# Contact PyPI support or use web interface

Automation Opportunities

GitHub Actions

Create .github/workflows/release.yml:

name: Release
on:
  push:
    tags:
      - 'v*'

jobs:
  goreleaser:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-go@v4
      - uses: goreleaser/goreleaser-action@v4
        with:
          version: latest
          args: release --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  npm:
    needs: goreleaser
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          registry-url: 'https://registry.npmjs.org'
      - run: cd npm-package && npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

  pypi:
    needs: goreleaser
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
      - run: |
          cd integrations/mcp/server
          pip install build twine
          python -m build
          twine upload dist/*
        env:
          TWINE_USERNAME: __token__
          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}

Post-Release

After a successful release:

  1. Upgrade local beads-mcp installation to the new version:

    # If installed globally
    pip install --upgrade beads-mcp
    
    # If installed as a uv tool
    uv tool upgrade beads-mcp
    
    # Verify the new version
    pip show beads-mcp | grep Version
    
    # Restart Claude Code or MCP session to pick up the new version
    # The MCP server will load the newly installed version
    
  2. Forward-port the release branch to main — see Release Branches. Include the docs/cli-docs.pin bump and the docs/index.md release line.

  3. Verify the upgraded CLI:

    bd version
    bd doctor quick
    
  4. Announce on relevant channels (Twitter, blog, etc.)

  5. Close milestone on GitHub if using milestones

  6. Update project board if using project management

  7. Monitor for issues in the first 24-48 hours

Troubleshooting

"Tag already exists"

# Delete tag locally and remotely
git tag -d v0.22.0
git push origin :refs/tags/v0.22.0

# Recreate
git tag -a v0.22.0 -m "Release v0.22.0"
git push origin v0.22.0

"npm publish fails with EEXIST"

# Version already published, bump version
npm version patch
npm publish

"Binary download fails in npm postinstall"

# Ensure GitHub release is published first
# Check binary URL is correct
# Verify version matches in package.json and GitHub release

"GoReleaser build fails"

# Check .goreleaser.yml syntax
goreleaser check

# Test build locally
goreleaser build --snapshot --clean

Version Numbering

Beads follows Semantic Versioning:

  • MAJOR (x.0.0): Removals and incompatible interface changes — a command, flag, config key, schema table or published Go API that is deleted or changes shape such that a caller written against the old one cannot be fixed by changing its inputs.
  • MINOR (0.x.0): New features, plus documented behavioral changes that ship with migration notes. A command that starts refusing input it used to accept, changes a default, or changes which rows it returns is a minor bump when the change is written up in CHANGELOG.md with the migration step and the opt-out. It is not a major bump: the interface is unchanged and the caller keeps working after a documented adjustment.
  • PATCH (0.0.x): Bug fixes, no behavioral change beyond the bug.

The MINOR clause is a description of practice, not a loophole. It carries an obligation: every behavioral break in a minor release must appear in CHANGELOG.md under that release, name its override or migration step, and be summarized in cmd/bd/info.go so bd info --whats-new surfaces it to agents. A behavioral break that is not documented that way is a bug in the release, not a minor bump.

1.3.0 is a worked example. It ships seven documented behavioral breaks — bd update --status <done-status> enforcing close policy, bd search including closed issues, the interactive-only last-touched fallback, bd human list status handling, bd dolt push remote-adoption consent, Dolt port precedence over BEADS_DOLT_PORT, and actor -- decoding — plus a schema migration and a flag rename (--profile → --cpu-profile). Every one has a CHANGELOG entry with its override, and the release is a MINOR bump.

Examples:

  • 0.21.5 → 0.22.0: New features (minor bump)
  • 0.22.0 → 0.22.1: Bug fix (patch bump)
  • 1.2.2 → 1.3.0: New features plus documented behavioral breaks with migration notes (minor bump)
  • 0.22.1 → 1.0.0: Stable release (major bump)

Prereleases: append a SemVer prerelease identifier for release candidates, e.g. 1.1.0-rc.1. Prerelease tags publish a GitHub prerelease only and stay off the stable Homebrew/PyPI/npm channels — see Prerelease / Release Candidate (RC) Workflow.

Release Cadence

  • Minor releases: Every 2-4 weeks (new features)
  • Patch releases: As needed (bug fixes)
  • Major releases: When breaking changes are necessary

Questions?