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>
This commit is contained in:
parent
ed7c268bb3
commit
b3ef65c854
30 changed files with 1186 additions and 395 deletions
|
|
@ -134,6 +134,20 @@ needs = ["preflight-git"]
|
|||
description = """
|
||||
Ensure we're up to date with origin and branch is properly synced.
|
||||
|
||||
**Every `origin/...` below means the branch you are RELEASING FROM, which is
|
||||
`release/x.y.z` — never `main`.** Resetting a release branch onto main's tip
|
||||
destroys the reviewed release-prep commit and leaves you tagging an untested
|
||||
main SHA, which is exactly the failure the release-branch policy exists to
|
||||
prevent. Pin the name first and use the variable:
|
||||
|
||||
```bash
|
||||
# The branch you are releasing from. For a prerelease this is still the BASE
|
||||
# version's branch: an RC for 1.3.0 is cut on release/1.3.0.
|
||||
REL_BRANCH="release/1.3.0"
|
||||
|
||||
git rev-parse --abbrev-ref HEAD # must equal $REL_BRANCH
|
||||
```
|
||||
|
||||
```bash
|
||||
# Fetch latest from origin
|
||||
git fetch origin
|
||||
|
|
@ -155,21 +169,20 @@ git pull --rebase
|
|||
Recovering from divergence:
|
||||
If your branch has diverged from origin (e.g., after a botched commit):
|
||||
```bash
|
||||
# Option 1: Reset to origin (loses local commits)
|
||||
git reset --hard origin/main
|
||||
|
||||
# Option 2: Rebase local commits on top of origin
|
||||
git rebase origin/main
|
||||
|
||||
# Option 3: Create a backup branch first
|
||||
# Option 1: Back up first, ALWAYS
|
||||
git branch backup-before-release
|
||||
git reset --hard origin/main
|
||||
|
||||
# Option 2: Reset to the release branch's origin (loses local commits)
|
||||
git reset --hard "origin/$REL_BRANCH"
|
||||
|
||||
# Option 3: Rebase local commits on top of it
|
||||
git rebase "origin/$REL_BRANCH"
|
||||
```
|
||||
|
||||
After pulling, verify sync:
|
||||
```bash
|
||||
git status -sb
|
||||
# Should show: "## main...origin/main" (no ahead/behind)
|
||||
# Should show: "## release/1.3.0...origin/release/1.3.0" (no ahead/behind)
|
||||
```
|
||||
"""
|
||||
|
||||
|
|
@ -326,158 +339,68 @@ Focus on workflow-impacting changes agents need to know.
|
|||
"""
|
||||
|
||||
[[steps]]
|
||||
id = "bump-version-go"
|
||||
title = "Bump version in version.go"
|
||||
id = "bump-versions"
|
||||
title = "Bump every version reference"
|
||||
needs = ["update-info-go"]
|
||||
description = """
|
||||
Update the Go version constant.
|
||||
Run the one script that owns every version reference.
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
sed -i '' 's/Version = "[^"]*"/Version = "{{version}}"/' cmd/bd/version.go
|
||||
|
||||
# Linux
|
||||
sed -i 's/Version = "[^"]*"/Version = "{{version}}"/' cmd/bd/version.go
|
||||
./scripts/update-versions.sh {{version}}
|
||||
```
|
||||
|
||||
This is the ONLY sanctioned way to bump. Hand-rolled sed per file is how the
|
||||
set drifts: this formula used to carry its own copies and pointed at a
|
||||
`claude-plugin/` path that has not existed since the plugins moved under
|
||||
`plugins/beads/`, while missing the copilot plugin, the MCP lockfile and the
|
||||
tracked git-hook markers entirely — so it would have failed outright, or
|
||||
shipped inconsistent versions, on every step after the stale path.
|
||||
|
||||
`scripts/update-versions.sh` rewrites, in one pass:
|
||||
|
||||
- `cmd/bd/version.go` — the canonical version everything else is compared to
|
||||
- `plugins/beads/.claude-plugin/plugin.json`
|
||||
- `plugins/beads/.codex-plugin/plugin.json`
|
||||
- `plugins/beads/.copilot-plugin/plugin.json`
|
||||
- `.claude-plugin/marketplace.json`
|
||||
- `integrations/beads-mcp/pyproject.toml`
|
||||
- `integrations/beads-mcp/src/beads_mcp/__init__.py`
|
||||
- `integrations/beads-mcp/uv.lock` — via `uv lock`
|
||||
- `npm-package/package.json`
|
||||
- `.githooks/*` — the `BEGIN`/`END BEADS INTEGRATION v<version>` markers
|
||||
- `default.nix`
|
||||
- `cmd/bd/winres/winres.json`, `cmd/bd/winres/manifest.xml`
|
||||
- `README.md` — the static Alpha badge, if one is present (it is not today;
|
||||
README uses live npm/PyPI/GitHub badges)
|
||||
|
||||
Two of those have burned a release before, so check the script's output rather
|
||||
than assuming:
|
||||
|
||||
- **`uv` must be installed.** Without it the script WARNS and leaves
|
||||
`uv.lock` stale. The release workflow's MCP gate runs `uv sync --locked`,
|
||||
which fails only in the tag-triggered run — after the tag exists and can no
|
||||
longer be rewritten. That burned v1.1.1 and cost v1.1.0 and v1.1.2 their
|
||||
first runs. If you see `uv not found` or `uv lock failed`, stop and fix it:
|
||||
```bash
|
||||
uv lock --directory integrations/beads-mcp
|
||||
```
|
||||
- **The `.githooks/*` markers are rewritten wholesale**, not matched against
|
||||
the current version, because they can already be drifted when the bump runs
|
||||
(they still said v1.1.0 during the v1.2.0 bump).
|
||||
|
||||
Not covered here, by design: `CHANGELOG.md` and `cmd/bd/info.go` (earlier
|
||||
steps), and `default.nix`'s `vendorHash` (next step).
|
||||
|
||||
Verify:
|
||||
```bash
|
||||
grep 'Version = ' cmd/bd/version.go
|
||||
```
|
||||
"""
|
||||
|
||||
[[steps]]
|
||||
id = "bump-plugin-json"
|
||||
title = "Bump version in plugin JSON files"
|
||||
needs = ["bump-version-go"]
|
||||
description = """
|
||||
Update Claude plugin manifest versions.
|
||||
|
||||
```bash
|
||||
# macOS/Linux with jq
|
||||
jq '.version = "{{version}}"' claude-plugin/.claude-plugin/plugin.json > tmp && mv tmp claude-plugin/.claude-plugin/plugin.json
|
||||
jq '.plugins[0].version = "{{version}}"' .claude-plugin/marketplace.json > tmp && mv tmp .claude-plugin/marketplace.json
|
||||
```
|
||||
|
||||
Verify:
|
||||
```bash
|
||||
jq -r '.version' claude-plugin/.claude-plugin/plugin.json
|
||||
jq -r '.plugins[0].version' .claude-plugin/marketplace.json
|
||||
```
|
||||
"""
|
||||
|
||||
[[steps]]
|
||||
id = "bump-mcp-python"
|
||||
title = "Bump version in MCP Python package"
|
||||
needs = ["bump-plugin-json"]
|
||||
description = """
|
||||
Update the beads-mcp Python package version.
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
sed -i '' 's/version = "[^"]*"/version = "{{version}}"/' integrations/beads-mcp/pyproject.toml
|
||||
sed -i '' 's/__version__ = "[^"]*"/__version__ = "{{version}}"/' integrations/beads-mcp/src/beads_mcp/__init__.py
|
||||
|
||||
# Linux
|
||||
sed -i 's/version = "[^"]*"/version = "{{version}}"/' integrations/beads-mcp/pyproject.toml
|
||||
sed -i 's/__version__ = "[^"]*"/__version__ = "{{version}}"/' integrations/beads-mcp/src/beads_mcp/__init__.py
|
||||
```
|
||||
|
||||
Verify:
|
||||
```bash
|
||||
grep 'version = ' integrations/beads-mcp/pyproject.toml | head -1
|
||||
grep '__version__ = ' integrations/beads-mcp/src/beads_mcp/__init__.py
|
||||
```
|
||||
"""
|
||||
|
||||
[[steps]]
|
||||
id = "bump-npm-package"
|
||||
title = "Bump version in npm package"
|
||||
needs = ["bump-mcp-python"]
|
||||
description = """
|
||||
Update the npm package version.
|
||||
|
||||
```bash
|
||||
# macOS/Linux with jq
|
||||
jq '.version = "{{version}}"' npm-package/package.json > tmp && mv tmp npm-package/package.json
|
||||
```
|
||||
|
||||
Verify:
|
||||
```bash
|
||||
jq -r '.version' npm-package/package.json
|
||||
```
|
||||
"""
|
||||
|
||||
[[steps]]
|
||||
id = "bump-winres"
|
||||
title = "Bump version in Windows resource metadata"
|
||||
needs = ["bump-npm-package"]
|
||||
description = """
|
||||
Update Windows PE resource metadata.
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
sed -i '' 's/"file_version": "[^"]*"/"file_version": "{{version}}"/' cmd/bd/winres/winres.json
|
||||
sed -i '' 's/"product_version": "[^"]*"/"product_version": "{{version}}"/' cmd/bd/winres/winres.json
|
||||
sed -i '' 's/"FileVersion": "[^"]*"/"FileVersion": "{{version}}"/' cmd/bd/winres/winres.json
|
||||
sed -i '' 's/"ProductVersion": "[^"]*"/"ProductVersion": "{{version}}"/' cmd/bd/winres/winres.json
|
||||
sed -i '' 's/version="[0-9][^"]*\\.0"/version="{{version}}.0"/' cmd/bd/winres/manifest.xml
|
||||
|
||||
# Linux
|
||||
sed -i 's/"file_version": "[^"]*"/"file_version": "{{version}}"/' cmd/bd/winres/winres.json
|
||||
sed -i 's/"product_version": "[^"]*"/"product_version": "{{version}}"/' cmd/bd/winres/winres.json
|
||||
sed -i 's/"FileVersion": "[^"]*"/"FileVersion": "{{version}}"/' cmd/bd/winres/winres.json
|
||||
sed -i 's/"ProductVersion": "[^"]*"/"ProductVersion": "{{version}}"/' cmd/bd/winres/winres.json
|
||||
sed -i 's/version="[0-9][^"]*\\.0"/version="{{version}}.0"/' cmd/bd/winres/manifest.xml
|
||||
```
|
||||
|
||||
Verify:
|
||||
```bash
|
||||
grep '{{version}}' cmd/bd/winres/winres.json
|
||||
grep 'version="{{version}}.0"' cmd/bd/winres/manifest.xml
|
||||
```
|
||||
"""
|
||||
|
||||
[[steps]]
|
||||
id = "bump-readme"
|
||||
title = "Check README static version references"
|
||||
needs = ["bump-winres"]
|
||||
description = """
|
||||
README.md currently uses live npm/PyPI/GitHub release badges instead of a static
|
||||
Alpha version string. Verify no old static version badge needs updating.
|
||||
|
||||
```bash
|
||||
rg 'Alpha \\(v|v[0-9]+\\.[0-9]+\\.[0-9]+' README.md || true
|
||||
```
|
||||
|
||||
If a static release reference is reintroduced later, update it here.
|
||||
"""
|
||||
|
||||
[[steps]]
|
||||
id = "bump-default-nix"
|
||||
title = "Bump version in default.nix"
|
||||
needs = ["bump-readme"]
|
||||
description = """
|
||||
Update the Nix package version.
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
sed -i '' 's/version = "[^"]*";/version = "{{version}}";/' default.nix
|
||||
|
||||
# Linux
|
||||
sed -i 's/version = "[^"]*";/version = "{{version}}";/' default.nix
|
||||
```
|
||||
|
||||
Verify:
|
||||
```bash
|
||||
grep 'version = ' default.nix
|
||||
git diff --stat
|
||||
```
|
||||
"""
|
||||
|
||||
[[steps]]
|
||||
id = "update-vendorhash"
|
||||
title = "Update Nix vendorHash if needed"
|
||||
needs = ["bump-default-nix"]
|
||||
needs = ["bump-versions"]
|
||||
description = """
|
||||
Update vendorHash if go.mod/go.sum changed since last release.
|
||||
|
||||
|
|
@ -533,21 +456,45 @@ id = "verify-versions"
|
|||
title = "Verify version consistency"
|
||||
needs = ["stamp-changelog"]
|
||||
description = """
|
||||
Confirm all versions match {{version}}.
|
||||
Run the gate, not a hand-listed grep pile — the grep list is what drifts.
|
||||
|
||||
```bash
|
||||
grep 'Version = ' cmd/bd/version.go
|
||||
jq -r '.version' claude-plugin/.claude-plugin/plugin.json
|
||||
jq -r '.plugins[0].version' .claude-plugin/marketplace.json
|
||||
jq -r '.version' npm-package/package.json
|
||||
grep 'version = ' integrations/beads-mcp/pyproject.toml
|
||||
grep '__version__ = ' integrations/beads-mcp/src/beads_mcp/__init__.py
|
||||
grep 'version = ' default.nix
|
||||
grep '{{version}}' cmd/bd/winres/winres.json
|
||||
grep 'version="{{version}}.0"' cmd/bd/winres/manifest.xml
|
||||
./scripts/check-versions.sh
|
||||
```
|
||||
|
||||
All should show {{version}}.
|
||||
`scripts/check-versions.sh` reads the canonical version out of
|
||||
`cmd/bd/version.go` and compares the gated files against it: all three plugin
|
||||
manifests (claude, codex, copilot), the marketplace, the MCP pyproject /
|
||||
`__init__.py` / `uv.lock` pin (plus `uv lock --check` for freshness when `uv`
|
||||
is present), the npm package, both `BEADS INTEGRATION` markers in every
|
||||
`.githooks/*` file, and the Windows PE metadata in `winres.json` and
|
||||
`manifest.xml`. It exits non-zero on any mismatch and names the file. This is
|
||||
the same script the release-tag pre-push hook and CI run, so a green run here
|
||||
is the real signal.
|
||||
|
||||
It must print `✓ Version files in sync at: {{version}}` before you continue.
|
||||
|
||||
**If it fails, do NOT just re-run the bump — that is a no-op here.**
|
||||
`update-versions.sh` derives the OLD version from `cmd/bd/version.go`, which by
|
||||
this point already reads `{{version}}`, so its substitutions rewrite
|
||||
`{{version}} -> {{version}}` and leave the drifted file exactly as it was while
|
||||
printing a green "Version constants updated". Only the `.githooks` markers
|
||||
(rewritten wholesale) and `uv.lock` (regenerated) heal on a re-run. The script
|
||||
prints the three remedies that do work; the usual one is to edit the named file
|
||||
to `{{version}}` and re-run the check.
|
||||
|
||||
`check-versions.sh` does NOT gate `default.nix` or `README.md`. Confirm
|
||||
`default.nix` yourself:
|
||||
|
||||
```bash
|
||||
grep 'version = ' default.nix # should be {{version}}
|
||||
```
|
||||
|
||||
(For a prerelease, do not expect the version string to appear uniformly in the
|
||||
winres files: `file_version`/`product_version` and the manifest's four-part
|
||||
version carry the BASE version because PE fields must be purely numeric, while
|
||||
`FileVersion`/`ProductVersion` carry the full `{{version}}`. check-versions.sh
|
||||
now encodes that split, so let it do the checking.)
|
||||
"""
|
||||
|
||||
[[steps]]
|
||||
|
|
@ -566,37 +513,74 @@ Review the commit to ensure all expected files are included.
|
|||
"""
|
||||
|
||||
[[steps]]
|
||||
id = "create-tag"
|
||||
title = "Create release tag"
|
||||
id = "push-main"
|
||||
title = "Land the release prep as a PR"
|
||||
needs = ["commit-release"]
|
||||
description = """
|
||||
Create annotated git tag.
|
||||
Releases are cut from `release/x.y.z`, not from the tip of `main` — see the
|
||||
"Release Branches" section of RELEASING.md. **Nothing is pushed straight to the
|
||||
release branch, and nothing is tagged before the PR merges.**
|
||||
|
||||
The branch is named for the BASE version: a `1.3.0-rc.1` run still targets
|
||||
`release/1.3.0`. Derive it rather than substituting `{{version}}` directly,
|
||||
which would name a branch nothing ever creates and fail with
|
||||
`src refspec ... does not match any`:
|
||||
|
||||
```bash
|
||||
BASE="$(printf '%s' "{{version}}" | sed 's/-.*//')"
|
||||
REL_BRANCH="release/$BASE"
|
||||
echo "$REL_BRANCH"
|
||||
```
|
||||
|
||||
Create the prep branch, push it, and open the PR:
|
||||
|
||||
```bash
|
||||
git checkout -b "release-prep/v{{version}}"
|
||||
git push -u origin "release-prep/v{{version}}"
|
||||
gh pr create --base "$REL_BRANCH" --label status/needs-review-auto
|
||||
```
|
||||
|
||||
Wait for it to merge, then take the merged state:
|
||||
|
||||
```bash
|
||||
git checkout "$REL_BRANCH" && git pull
|
||||
```
|
||||
|
||||
After the release ships, every commit that landed only on the release branch
|
||||
needs a forward-port PR to `main`, the version bump included:
|
||||
|
||||
```bash
|
||||
git log --oneline "main..$REL_BRANCH"
|
||||
```
|
||||
"""
|
||||
|
||||
[[steps]]
|
||||
id = "create-tag"
|
||||
title = "Create release tag on the merged commit"
|
||||
needs = ["push-main"]
|
||||
description = """
|
||||
Create the annotated tag on the MERGED commit, with the release branch checked
|
||||
out and pulled (previous step).
|
||||
|
||||
```bash
|
||||
git rev-parse --abbrev-ref HEAD # must be the release branch, not the prep branch
|
||||
git tag -a v{{version}} -m "Release v{{version}}"
|
||||
```
|
||||
|
||||
Tagging before the merge is the failure to avoid, in two shapes. With branch
|
||||
protection on, the direct push is rejected after the tag already exists
|
||||
locally. With a squash merge, the tag points at a commit that is not an
|
||||
ancestor of the release branch — and goreleaser packages `CHANGELOG.md` *from
|
||||
the tag* into every published archive, so the release would ship the
|
||||
pre-review notes.
|
||||
|
||||
Verify: `git tag -l | tail -5`
|
||||
"""
|
||||
|
||||
[[steps]]
|
||||
id = "push-main"
|
||||
title = "Push to main"
|
||||
needs = ["create-tag"]
|
||||
description = """
|
||||
Push the release commit to origin.
|
||||
|
||||
```bash
|
||||
git push origin main
|
||||
```
|
||||
|
||||
If rejected, someone else pushed. Pull, rebase, try again.
|
||||
"""
|
||||
|
||||
[[steps]]
|
||||
id = "push-tag"
|
||||
title = "Push release tag"
|
||||
needs = ["push-main"]
|
||||
needs = ["create-tag"]
|
||||
description = """
|
||||
Push the version tag to trigger CI release.
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@
|
|||
"name": "beads",
|
||||
"source": "./plugins/beads",
|
||||
"description": "AI-supervised issue tracker for coding workflows",
|
||||
"version": "1.2.2"
|
||||
"version": "1.3.0"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
#!/usr/bin/env sh
|
||||
# --- BEGIN BEADS INTEGRATION v1.2.2 ---
|
||||
# --- BEGIN BEADS INTEGRATION v1.3.0 ---
|
||||
# This section is managed by beads. Do not remove these markers.
|
||||
if command -v bd >/dev/null 2>&1; then
|
||||
export BD_GIT_HOOK=1
|
||||
|
|
@ -56,4 +56,4 @@ if command -v bd >/dev/null 2>&1; then
|
|||
fi
|
||||
if [ "$_bd_exit" -ne 0 ]; then exit "$_bd_exit"; fi
|
||||
fi
|
||||
# --- END BEADS INTEGRATION v1.2.2 ---
|
||||
# --- END BEADS INTEGRATION v1.3.0 ---
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
#!/usr/bin/env sh
|
||||
# --- BEGIN BEADS INTEGRATION v1.2.2 ---
|
||||
# --- BEGIN BEADS INTEGRATION v1.3.0 ---
|
||||
# This section is managed by beads. Do not remove these markers.
|
||||
if command -v bd >/dev/null 2>&1; then
|
||||
export BD_GIT_HOOK=1
|
||||
|
|
@ -56,4 +56,4 @@ if command -v bd >/dev/null 2>&1; then
|
|||
fi
|
||||
if [ "$_bd_exit" -ne 0 ]; then exit "$_bd_exit"; fi
|
||||
fi
|
||||
# --- END BEADS INTEGRATION v1.2.2 ---
|
||||
# --- END BEADS INTEGRATION v1.3.0 ---
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@ if [ -n "$staged_go_files" ]; then
|
|||
echo "$staged_go_files" | xargs git add
|
||||
fi
|
||||
|
||||
# --- BEGIN BEADS INTEGRATION v1.2.2 ---
|
||||
# --- BEGIN BEADS INTEGRATION v1.3.0 ---
|
||||
# This section is managed by beads. Do not remove these markers.
|
||||
if command -v bd >/dev/null 2>&1; then
|
||||
export BD_GIT_HOOK=1
|
||||
|
|
@ -97,4 +97,4 @@ if command -v bd >/dev/null 2>&1; then
|
|||
fi
|
||||
if [ "$_bd_exit" -ne 0 ]; then exit "$_bd_exit"; fi
|
||||
fi
|
||||
# --- END BEADS INTEGRATION v1.2.2 ---
|
||||
# --- END BEADS INTEGRATION v1.3.0 ---
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ fi
|
|||
|
||||
exec < <(printf '%s\n' "$push_refs")
|
||||
|
||||
# --- BEGIN BEADS INTEGRATION v1.2.2 ---
|
||||
# --- BEGIN BEADS INTEGRATION v1.3.0 ---
|
||||
# This section is managed by beads. Do not remove these markers.
|
||||
if command -v bd >/dev/null 2>&1; then
|
||||
export BD_GIT_HOOK=1
|
||||
|
|
@ -96,4 +96,4 @@ if command -v bd >/dev/null 2>&1; then
|
|||
fi
|
||||
if [ "$_bd_exit" -ne 0 ]; then exit "$_bd_exit"; fi
|
||||
fi
|
||||
# --- END BEADS INTEGRATION v1.2.2 ---
|
||||
# --- END BEADS INTEGRATION v1.3.0 ---
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
#!/usr/bin/env sh
|
||||
# --- BEGIN BEADS INTEGRATION v1.2.2 ---
|
||||
# --- BEGIN BEADS INTEGRATION v1.3.0 ---
|
||||
# This section is managed by beads. Do not remove these markers.
|
||||
if command -v bd >/dev/null 2>&1; then
|
||||
export BD_GIT_HOOK=1
|
||||
|
|
@ -56,4 +56,4 @@ if command -v bd >/dev/null 2>&1; then
|
|||
fi
|
||||
if [ "$_bd_exit" -ne 0 ]; then exit "$_bd_exit"; fi
|
||||
fi
|
||||
# --- END BEADS INTEGRATION v1.2.2 ---
|
||||
# --- END BEADS INTEGRATION v1.3.0 ---
|
||||
|
|
|
|||
2
.github/workflows/conformance.yml
vendored
2
.github/workflows/conformance.yml
vendored
|
|
@ -5,7 +5,7 @@ name: Conformance
|
|||
|
||||
on:
|
||||
pull_request:
|
||||
branches: [ main ]
|
||||
branches: [ main, 'release/**' ]
|
||||
merge_group:
|
||||
|
||||
concurrency:
|
||||
|
|
|
|||
6
.github/workflows/cross-version-smoke.yml
vendored
6
.github/workflows/cross-version-smoke.yml
vendored
|
|
@ -6,9 +6,11 @@ on:
|
|||
tags:
|
||||
- 'v*'
|
||||
|
||||
# On PR to main: test only the last 5 releases for fast feedback
|
||||
# On PR to main or a release branch: test only the last 5 releases for fast
|
||||
# feedback. Release-targeted PRs are exactly the ones where cross-version
|
||||
# upgrade breakage is most expensive to discover at tag time.
|
||||
pull_request:
|
||||
branches: [ main ]
|
||||
branches: [ main, 'release/**' ]
|
||||
|
||||
# Allow manual trigger with custom version count
|
||||
workflow_dispatch:
|
||||
|
|
|
|||
2
.github/workflows/pr-risk.yml
vendored
2
.github/workflows/pr-risk.yml
vendored
|
|
@ -2,7 +2,7 @@ name: PR Risk
|
|||
|
||||
on:
|
||||
pull_request:
|
||||
branches: [ main ]
|
||||
branches: [ main, 'release/**' ]
|
||||
merge_group:
|
||||
|
||||
concurrency:
|
||||
|
|
|
|||
5
.github/workflows/pr.yml
vendored
5
.github/workflows/pr.yml
vendored
|
|
@ -2,7 +2,10 @@ name: PR
|
|||
|
||||
on:
|
||||
pull_request:
|
||||
branches: [ main ]
|
||||
# release/** is here because release-prep and release-fix PRs are based on
|
||||
# the release branch, not on main. Without it they run almost no CI and the
|
||||
# first full signal is the tag build, where a failure burns the tag.
|
||||
branches: [ main, 'release/**' ]
|
||||
merge_group:
|
||||
|
||||
concurrency:
|
||||
|
|
|
|||
2
.github/workflows/regression.yml
vendored
2
.github/workflows/regression.yml
vendored
|
|
@ -5,7 +5,7 @@ on:
|
|||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
branches: [main, 'release/**']
|
||||
# Allow manual trigger
|
||||
workflow_dispatch:
|
||||
|
||||
|
|
|
|||
600
CHANGELOG.md
600
CHANGELOG.md
|
|
@ -7,6 +7,162 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|||
|
||||
## [Unreleased]
|
||||
|
||||
## [1.3.0] - 2026-08-28
|
||||
|
||||
The first tested release off `main` since the 1.1 line. [1.2.2] was a recovery
|
||||
release that re-shipped the v1.1.2 code under a higher version number, so a
|
||||
v1.2.2 user is running 1.1-era code and meets **everything** below at once:
|
||||
the changes listed here, plus the [1.2.1] changes that release deliberately
|
||||
withheld. Read the upgrade notes before installing.
|
||||
|
||||
### Upgrade notes
|
||||
|
||||
**On an embedded or local store, the first invocation migrates your schema, in
|
||||
place, from v53 to v66.** A v1.2.2 (or any 1.1.x) database sits at main-series
|
||||
schema v53; this binary knows v66, so the first command that opens the store
|
||||
applies 13 main-series migrations, `0054_add_lease_columns` through
|
||||
`0066_add_events_journal_actor`. Two of those passes rewrite rows rather than
|
||||
just reshaping tables — the aux-row id rekey and the `events` dolt_ignore flip
|
||||
described under **Changed** — so on a large store the first invocation is
|
||||
*noticeably* slower than the ones after it. It is crash-resumable and picks up
|
||||
where it left off, but do not interrupt it if you can avoid it.
|
||||
|
||||
**A shared Dolt sql-server is never auto-migrated** (#5920, #6048): migrating it
|
||||
promotes the schema for every client at once, so it waits for explicit consent
|
||||
via `bd migrate schema`. Remote-backed stores keep their existing
|
||||
designated-migrator gate. Upgrade all of that server's clients *first* — see
|
||||
[Shared servers](https://beads.gascity.com/getting-started/upgrading#shared-servers).
|
||||
|
||||
**The counter restarts partway through, and that is not a loop.** The
|
||||
clone-local (dolt_ignored) series runs after the main one, through the same
|
||||
printer and its own numbering, and it moves 0011 → 0026 on this upgrade. So the
|
||||
run is about **28 migrations**, not 13, and what you see on stderr is 13 lines
|
||||
counting up to 0066 followed by 15 lines starting again at 0012:
|
||||
|
||||
```
|
||||
Applying migration 0065: widen_wisp_comments_text…
|
||||
Applying migration 0066: add_events_journal_actor…
|
||||
Applying migration 0012: create_leases… ← clone-local series, not a restart
|
||||
```
|
||||
|
||||
A counter that jumps backwards is the signature operators kill runs over. Let
|
||||
it finish.
|
||||
|
||||
Progress prints only when stderr is a terminal. Piped and CI runs see nothing
|
||||
at all, which is deliberate — a silent-looking CI upgrade is not a stuck one.
|
||||
|
||||
**Back up first, with the binary you have now.** Take the backup *before* you
|
||||
install 1.3.0. Under the new binary `bd export` triggers the auto-migration
|
||||
before it exports, so a snapshot taken afterwards is a post-migration snapshot
|
||||
and cannot protect you against the migration going wrong. On a remote-backed
|
||||
store, finish syncing with the old binary too: once 1.3.0 is installed the
|
||||
pending-migration gate refuses `bd dolt push` and `bd dolt pull` as well, not
|
||||
just `bd migrate`.
|
||||
|
||||
```bash
|
||||
# with your CURRENT bd, before installing 1.3.0:
|
||||
bd dolt push # remote-backed stores only
|
||||
bd export --all -o .beads/backup/pre-1.3.0-$(date +%Y%m%d).jsonl
|
||||
```
|
||||
|
||||
A JSONL export is cheap, issue-complete, and importable by any bd version. If
|
||||
you want a Dolt-native snapshot that keeps history and config, configure a
|
||||
destination and sync it — **bare `bd backup` takes no backup**, it is a command
|
||||
group that prints help and exits 0:
|
||||
|
||||
```bash
|
||||
bd backup init <path-or-dolthub-url> # once, to configure a destination
|
||||
bd backup sync # take the snapshot
|
||||
```
|
||||
|
||||
**Upgrade every client that shares a store, together.** The forward schema-skew
|
||||
guard means an older co-resident binary — a second `bd` earlier in `PATH`, a
|
||||
long-running `bd serve`, another clone's cron job — refuses a database migrated
|
||||
past what it knows, rather than proceeding blind. That is the guard working, not
|
||||
a bug, but it makes a mixed-version fleet a broken fleet: one machine running
|
||||
1.3.0 takes the whole store forward and every 1.2.2 client stops. Run
|
||||
`which -a bd` after installing, and on a remote-backed store follow the existing
|
||||
designated-migrator procedure (one clone migrates and pushes; the rest pull or
|
||||
re-clone). See
|
||||
[Upgrading](https://beads.gascity.com/getting-started/upgrading) for the
|
||||
per-install-method recipes and the multi-clone flow.
|
||||
|
||||
**If you need to go back**, the rollback is a schema-cursor rollback, not a
|
||||
downgrade of the data: the procedure is written up in the
|
||||
[recovery runbook](https://beads.gascity.com/recovery/accidental-1-2-1-release)
|
||||
(repo copy: `docs/recovery/accidental-1-2-1-release.md`). Its worked example is
|
||||
the v53↔v65 case from the accidental 1.2.1 release; the steps are the same for
|
||||
v66, with the version numbers adjusted.
|
||||
|
||||
### Breaking changes for v1.2.2 users
|
||||
|
||||
**This is a highlights list, not the complete set.** A v1.2.2 user is crossing
|
||||
two releases at once, and the breaks below are the ones most likely to stop a
|
||||
script or a service. The full set is the `[1.2.1]` section further down plus the
|
||||
**Changed** section here — read `[1.2.1]` in full before upgrading, since
|
||||
[1.2.2] withheld it and v1.2.1 itself was pulled, so nobody on the supported
|
||||
line has seen it.
|
||||
|
||||
After upgrading, `bd upgrade review` prints exactly the entries between the
|
||||
version you were running and this one. (Prefer it to `bd info --whats-new`,
|
||||
which dumps the entire release history.)
|
||||
|
||||
**Carried from [1.2.1] — never shipped to v1.2.2 users:**
|
||||
|
||||
- **`bd update --status <done-status>` now enforces close policy.** Moving an
|
||||
issue to `closed` (or any configured done-category status) via `bd update`,
|
||||
`bd batch update`, or the issueops facade refuses when the issue has open
|
||||
children or a live direct blocker, matching `bd close`. Override with
|
||||
`bd update --force` (`update <id> status=closed force=true` in `bd batch`;
|
||||
`UpdateRequest.ForceClosePolicy` for facade consumers). An unforced refusal
|
||||
rolls back the entire batch.
|
||||
- **`bd search` includes closed issues by default** (bd-t5yex). The dominant
|
||||
query is "was this already found/filed/fixed?", where excluding closed issues
|
||||
produced a false "no". Narrow with `--status open` to get the old behavior.
|
||||
`bd list` keeps its open-only default.
|
||||
- **The no-ID "last touched issue" fallback on `bd update` / `bd close` is
|
||||
interactive-only** (bd-m00pb,
|
||||
[#4839](https://github.com/gastownhall/beads/pull/4839)). A scripted
|
||||
`bd update $ID …` with an empty `$ID` now refuses in argument validation
|
||||
instead of mutating whatever was touched last. The fallback requires a
|
||||
terminal stdin; `BD_NON_INTERACTIVE=1` and `CI=1/true` also disable it. Set
|
||||
`BD_LAST_TOUCHED_FALLBACK=1` if a script genuinely relied on it.
|
||||
- **`bd human list` hides done/frozen and pinned beads by default, and
|
||||
validates `--status`** (#5332). It previously passed `--status` through
|
||||
unvalidated and showed closed beads. A `--status` typo is now an error rather
|
||||
than an empty list. Every bead *type* still shows.
|
||||
- **`bd dolt push` and `bd sync` no longer adopt a git-origin-derived Dolt
|
||||
remote without consent** (#5068). Both used to silently derive a remote from
|
||||
`git remote get-url origin`, persist `sync.remote`, commit that config change
|
||||
under your git identity, and upload the full issue history — which published
|
||||
a whole issue database to a public origin on a command the user believed
|
||||
targeted an already-configured remote. Adoption now prompts (defaulting to
|
||||
no) and fails closed non-interactively. `--yes`/`-y` consents ahead of time.
|
||||
- **`bd --readonly serve` is refused instead of binding a server that cannot do
|
||||
what it advertises.** On a Dolt SQL-server workspace the flag was previously a
|
||||
silent no-op and the server came up fully writable, so anything scripted as a
|
||||
"safe" read-only server **does not start after this upgrade** — drop the flag.
|
||||
Worth checking before you restart a long-running `bd serve` as part of the
|
||||
fleet upgrade above.
|
||||
- **`bd config list` and `GET /v0/beads/config` no longer enumerate the `kv.`
|
||||
plane**, which is where `bd remember` memories live. That closed an
|
||||
unauthenticated `GET /v0/beads/config` handing out every stored memory. A
|
||||
script that read memories out of `bd config list` now gets empty output rather
|
||||
than an error; use `bd kv` / `bd remember` instead.
|
||||
- **The published `backend` package drops orphan handling** (bd-gwryr).
|
||||
`backend.OrphanHandling` and its four constants, the `storage` originals they
|
||||
aliased, `BatchCreateOptions.OrphanHandling` and `issueops.CheckOrphan` are
|
||||
removed. They never did anything except cost a query, but a Go consumer that
|
||||
names them no longer compiles.
|
||||
|
||||
**New in 1.3.0** (full entries under **Changed**):
|
||||
|
||||
- An explicitly configured Dolt server port now outranks the ambient
|
||||
`BEADS_DOLT_PORT` environment variable.
|
||||
- Actor matching decodes an exact `--` run to `/` instead of collapsing it to a
|
||||
generic separator, so `gastown--mayor` matches `gastown/mayor` and stops
|
||||
matching `gastown__mayor`.
|
||||
|
||||
### Added
|
||||
|
||||
- **The events journal records WHO performed each mutation.** `bd_events_journal`
|
||||
|
|
@ -51,22 +207,207 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|||
concept, themes are labels here, and `--label theme:x` is the native way to
|
||||
say it.
|
||||
|
||||
- **New `*.gate.lock` files appear next to and inside `.beads`** ([#5046](https://github.com/gastownhall/beads/pull/5046),
|
||||
[#5093](https://github.com/gastownhall/beads/pull/5093)). A two-level
|
||||
cooperative gate now serializes the operations that cannot safely overlap —
|
||||
ordinary commands take it shared, maintenance like `bd backup restore` takes
|
||||
it exclusive. It is `flock`-based, so the file is the lock's *name*, not its
|
||||
state: the gate is created once (mode `0600`) and deliberately never deleted,
|
||||
because deleting it is how two processes end up holding two different locks
|
||||
for the same resource. Each gate sits *beside* what it guards, never inside
|
||||
it: the workspace gate for `<dir>/.beads` is `<dir>/.beads.gate.lock` in the
|
||||
project root, and the physical-root gate is `.beads/embeddeddolt.gate.lock` in
|
||||
the default embedded mode (`.beads/dolt.gate.lock` under a server layout;
|
||||
under the shared server it lives beside `~/.beads/shared-server/dolt` and
|
||||
never enters the workspace at all; a remote Dolt host has no physical gate).
|
||||
Both are covered by the `*.gate.lock*` pattern `bd doctor` maintains in the
|
||||
project and `.beads` gitignores, so an upgraded workspace picks up the ignore
|
||||
rule on the next `bd doctor --fix`; a workspace with no `.beads` directory is
|
||||
not gated at all, rather than scattering lock files into whatever directory
|
||||
`bd` was run from.
|
||||
|
||||
- **`sort` on `GET /v0/beads/issues`.** The listing served one order —
|
||||
`(created_at DESC, id ASC)` — because the cursor is a keyset position in it,
|
||||
and the spec said so in its own words: "the sort order is welded to the cursor
|
||||
contract, and a new order needs new surface." The cost of that welding fell on
|
||||
every client that wanted `bd list`'s ordering, because the only way to get it
|
||||
was to page the whole result set and re-sort locally. Measured over a
|
||||
1400-row store at the 200-row page an HTTP client actually uses, that is
|
||||
**7 requests plus a client-side comparator; `?sort=priority` is 1**
|
||||
(`TestProxiedServerListSortRetiresTheWalk`, which runs both strategies against
|
||||
a real `bd serve` and checks both against `bd list --json` row for row). It is
|
||||
the one cost on this surface that got worse as a project grew.
|
||||
|
||||
**Two values, and the set is closed.** `created` is the existing order, now
|
||||
spellable. `priority` is `(priority ASC, created_at DESC, id ASC)` — `bd
|
||||
list`'s flagless ordering, which is also what `bd list --sort priority`
|
||||
produces, so one served order retires the walk for both. The other seven
|
||||
orders `bd list --sort` takes are not offered: each value here is a cursor
|
||||
contract needing a key proven total, and `id` is a natural-numeric order no
|
||||
database expresses, `updated` moves on every write, `closed` is nullable, and
|
||||
`status`/`title`/`type`/`assignee` are mutable and unindexed.
|
||||
|
||||
**Absent `sort` still means `created`, permanently.** It is the compatibility
|
||||
contract for every client written before the parameter existed; changing it
|
||||
would alter which rows a truncated page contains, with no error to notice it
|
||||
by. A server that predates the parameter answers `param: "sort"` with
|
||||
`reason: "unknown_parameter"`, which is the per-parameter capability probe a
|
||||
client dispatches on to fall back.
|
||||
|
||||
**The cursor now carries its order, and a mismatch is refused.** This is the
|
||||
half that makes the parameter safe rather than merely useful. The token was
|
||||
base64 of `{t,i}` with no binding, so a `created`-order cursor replayed under
|
||||
`sort=priority` would have decoded perfectly and been read as a position in a
|
||||
different total order — a page that both skips and duplicates rows, served
|
||||
with a 200, undetectable by the client. Tokens are now `v2` with an explicit
|
||||
order member and decode refuses any token whose order differs from the
|
||||
request's, as `invalid_cursor` (documented recovery: restart paging).
|
||||
Outstanding `v1` tokens stay readable as the `created`-order positions they
|
||||
are, so **no traversal in flight has to restart**. This does not contradict
|
||||
"the token carries no filters": filters select the set, the order decides what
|
||||
the position means.
|
||||
|
||||
**`priority` is a mutable key**, which `created_at` is not, and the spec says
|
||||
so: under `created` only new rows move relative to a walk, while a priority
|
||||
update moves an existing row too, so it can be seen twice or missed. That is
|
||||
the already-documented "a cursor pins a position, not a snapshot" caveat
|
||||
reached by a second route, not a new class of error — unchanged data never
|
||||
skips or repeats under either order.
|
||||
|
||||
### Changed
|
||||
|
||||
- **Write commands now refuse to run while a MIGRATION-FREEZE sentinel sits
|
||||
at the town root** (dc-6jaq), mirroring the gate the gt CLI already applies
|
||||
to `gt mail send`/`nudge`/`sling`/`assign`. `bd create`/`update`/`close`/
|
||||
`remember`/`import` and every other command gated by `CheckReadonly`
|
||||
(~120 call sites, `bd q` included) now print `⛔ town is frozen for
|
||||
migration (by <operator>)` and exit 1 instead of writing to a store mid-
|
||||
migration. The check runs twice: once early in the root command, before
|
||||
version-bump auto-migration or JSONL auto-import can touch the store, and
|
||||
again at each write command's own chokepoint. Read commands (`list`,
|
||||
`show`, `ready`, …) keep working during a freeze — the same early check
|
||||
also skips version tracking and auto-migration for them, so a frozen store
|
||||
is never rewritten just because someone ran a read. `--dry-run`/`--inspect`
|
||||
previews are blocked at the per-command chokepoint instead, same as strict
|
||||
`--readonly` already blocks them. Clear the freeze with `gt migrate thaw`.
|
||||
- Shared Dolt databases (sql-server mode) no longer auto-apply schema
|
||||
migrations on a version bump. Migrating a shared database promotes the
|
||||
schema for every connected bd client at once and locks out clients still
|
||||
on an older binary, so bd now refuses without explicit consent: run
|
||||
`bd migrate schema` once after upgrading every client, or set
|
||||
`BD_ALLOW_REMOTE_MIGRATE=1` in scripted use. Reads keep working on the
|
||||
current schema meanwhile. Embedded (single-user) databases still
|
||||
auto-migrate silently, unchanged. (#5920)
|
||||
|
||||
- The smart migration gate's "auto-migrate as safe first-mover" and
|
||||
auto-fast-forward arms are now embedded-only. On a shared server the gate
|
||||
always stops for consent, because neither argument can observe the other
|
||||
clients attached to that server. (#5920, #4516)
|
||||
|
||||
- The newly exported Go packages (`backend`, `backend/conformance`, `beadserrors`,
|
||||
`issueops`, `journalops`, `memoryops`, `schema`, `test/conformance`) are marked
|
||||
EXPERIMENTAL: they are not yet covered by the project's compatibility promise and
|
||||
may change in a minor release. Pin an exact beads version and re-run the
|
||||
conformance suite on every bump.
|
||||
|
||||
- **The optimistic-concurrency token is now a JSON string** — responses carry
|
||||
`revision` as an opaque decimal string and `expected_version` must be sent as
|
||||
that string. JSON-number tokens exceeded JavaScript's 2^53 integer precision.
|
||||
This member never shipped in a tagged release.
|
||||
|
||||
- CI: migration-test and upgrade-smoke now seed and assert wisp-plane data
|
||||
(wisps, wisp deps/comments, leases, events, ignored-track cursor) across
|
||||
v1.0.1/v1.1.x/v1.2.2 → candidate upgrades.
|
||||
|
||||
- **`--profile` is now `--cpu-profile`, with no alias**
|
||||
([#5126](https://github.com/gastownhall/beads/pull/5126), bd-ugz). The
|
||||
persistent flag that writes a CPU profile is spelled `--cpu-profile`; the old
|
||||
`--profile` spelling is gone rather than deprecated, so it fails as an unknown
|
||||
flag instead of silently doing nothing. `--profile` is the conventional name
|
||||
for a *named configuration*, not for pprof output, and holding it hostage to
|
||||
a debugging aid nobody passes twice a year was the wrong trade. Scripts and
|
||||
aliases that profile bd need the new spelling.
|
||||
|
||||
- **Migration 0061 rekeys every events, comments, snapshot and
|
||||
compaction-snapshot row to a content-derived id**
|
||||
([#5150](https://github.com/gastownhall/beads/pull/5150), bd-ri8bd). Those
|
||||
four aux tables minted random UUIDv7 ids, which is fine for a single writer
|
||||
and wrong for replication: unversioned newest-wins replication has no merge
|
||||
pass, so two clones recording the same fact produced two rows that never
|
||||
converged. Ids are now UUIDv5 over a SHA-256 digest of the row's own content
|
||||
(frozen column order, plus the table name and a duplicate-disambiguating
|
||||
ordinal), so the same fact derives the same id everywhere and convergence is
|
||||
a property of the key rather than of a reconciliation step. New rows derive
|
||||
their id at insert; existing rows are converted by a **one-time bulk rekey**
|
||||
on the first open after upgrade, which is the main reason that invocation is
|
||||
slower than the ones after it. The pass is crash-resumable through a
|
||||
`local_metadata` sentinel and records completion clone-locally, so it runs
|
||||
once per clone and is not repeated on the next command. `wisp_events` and
|
||||
`wisp_comments` are deliberately excluded — they are clone-local and never
|
||||
merge. **Any external reference to an event, comment or snapshot id taken
|
||||
before the upgrade will not resolve afterwards.**
|
||||
|
||||
- **The `events` audit table is now clone-local**
|
||||
([#5162](https://github.com/gastownhall/beads/pull/5162), bd-red8u).
|
||||
Migration 0062 moves `events` onto the dolt_ignored plane in a self-committing
|
||||
drop/commit/recreate that preserves every row. Events are single-writer audit
|
||||
rows with low cross-machine value, and minting a versioned Dolt commit for
|
||||
each one was the dominant source of commit churn on a busy store. The
|
||||
consequence is the point: **`events` rows no longer replicate.** They keep
|
||||
full SQL durability locally and `bd history <id> --events` still reads them,
|
||||
but a pull no longer brings another machine's events over, and a push no
|
||||
longer sends yours. Events already committed before the flip stay in the
|
||||
remote's history until the next squash window. Comments stay versioned.
|
||||
|
||||
- **The `interactions.jsonl` audit sidecar is opt-in**
|
||||
([#4688](https://github.com/gastownhall/beads/pull/4688), fixes
|
||||
[#4687](https://github.com/gastownhall/beads/issues/4687)). `audit.enabled`
|
||||
now defaults to **false** and `bd init` no longer creates the file, so
|
||||
status/assignee/priority field-change logging writes nothing unless you ask
|
||||
for it. Set `audit.enabled=true` (or `BD_AUDIT_ENABLED=1`) to restore the old
|
||||
behavior. The database-backed replacement is `bd history <id> --events`, which
|
||||
needs no sidecar. Anything that read `.beads/interactions.jsonl` on the
|
||||
assumption it would exist needs the config key set.
|
||||
|
||||
- **`bd import` refuses a redirected stdin rather than quietly ignoring it**
|
||||
([#5171](https://github.com/gastownhall/beads/pull/5171), bd-axluy). Bare
|
||||
`bd import` imports the default JSONL, and `bd import -` imports stdin; a
|
||||
`bd import < file.jsonl` looked like the second and behaved like the first,
|
||||
importing a different file than the one on the command line with no way to
|
||||
notice. With stdin redirected, no `-`, and no named source, `bd import` now
|
||||
errors and names both fixes. `/dev/null` is a character device, so a scripted
|
||||
bare `bd import` under a subprocess still imports the default file as before.
|
||||
|
||||
- **Auto-backup defaults to off under a Dolt sql-server** (wy-zrmqr). The
|
||||
automatic backup used to switch itself on whenever a git remote existed,
|
||||
regardless of storage mode — which on one shared sql-server meant ~31 clients
|
||||
independently deciding to back up the same database, pinning its CPU. The
|
||||
default is now off in server, proxied-server and shared-server modes (and in
|
||||
nocgo builds, which are always server-backed); embedded mode is unchanged and
|
||||
still enables it when a git remote is present. An explicitly configured
|
||||
`backup.enabled` (or `BD_BACKUP_ENABLED`) always wins over the default, and
|
||||
`bd config get backup.enabled` now prints the effective value with its source
|
||||
— `default (auto: off in sql-server mode)` — rather than a bare `false` that
|
||||
could not be told apart from a configured one.
|
||||
|
||||
- **`bd hooks install --chain` and `--force` are accepted no-ops**
|
||||
([#5284](https://github.com/gastownhall/beads/pull/5284), bd-5vdt8). Managed
|
||||
`BEGIN`/`END BEADS INTEGRATION` marker sections made both flags meaningless:
|
||||
an install now replaces only the content between its own markers, so content
|
||||
outside them is *always* preserved (what `--force` used to negate) and an
|
||||
existing hook *always* keeps running alongside the bd section (what `--chain`
|
||||
used to request). The flags remain registered so existing invocations do not
|
||||
break, and `--json` still echoes them, but neither changes what is written.
|
||||
A hook with no markers is handled by shape: a legacy bd hook is replaced, and
|
||||
a foreign one gets a one-time `<hook>.backup` sidecar before the section is
|
||||
injected. Symlinked and git-tracked hook paths are refused outright, before
|
||||
anything is written.
|
||||
|
||||
- **Write commands refuse to run while a migration freeze marker is present**
|
||||
(dc-6jaq). When a file named `MIGRATION-FREEZE` exists in the workspace
|
||||
directory, the working directory, or any ancestor of either — or at the
|
||||
path named by `BD_MIGRATION_FREEZE_FILE`, which is authoritative when set
|
||||
— `bd create`/`update`/`close`/`remember`/`import` and every other write
|
||||
command (~120 call sites, `bd q` included), plus the destructive
|
||||
`bd init --reinit-local` and `bd bootstrap`, print `⛔ workspace is frozen
|
||||
for migration` naming the marker's path and exit **14**, a distinct code
|
||||
scripts can branch on, instead of writing to a store mid-migration.
|
||||
Operators freeze a workspace by creating the file (optionally
|
||||
`operator<TAB>RFC3339 timestamp<TAB>reason` on one line, echoed back in
|
||||
the refusal) and thaw it by removing the file. Read commands (`list`,
|
||||
`show`, `ready`, …) keep working during a freeze, and bd's own maintenance
|
||||
stands down with them — version tracking, auto-migration, JSONL
|
||||
auto-import, Dolt auto-commit, auto-backup, auto-export and auto-push are
|
||||
all skipped, so a frozen store is never rewritten just because someone ran
|
||||
a read. A running `bd serve` is not gated: stop it before freezing. If bd
|
||||
cannot tell whether a marker is present, it refuses rather than assuming
|
||||
the workspace is open.
|
||||
|
||||
- **`bd dep add` names the implicit `type=blocks` default, but only to an
|
||||
interactive operator** (#5854). Creating an edge with no `-t/--type` silently
|
||||
|
|
@ -173,6 +514,125 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|||
|
||||
### Fixed
|
||||
|
||||
- **Server-mode issue mutations no longer revert concurrent writers' committed
|
||||
rows** ([#5740](https://github.com/gastownhall/beads/pull/5740)). The
|
||||
issue-mutation path ran `DOLT_ADD`/`DOLT_COMMIT` inside its still-open SQL
|
||||
transaction; `DOLT_ADD` stages the whole table as of the transaction's
|
||||
BEGIN-time root, and the Dolt commit was minted before the commit-time merge
|
||||
that reconciles concurrent writers — so a mutation could silently write every
|
||||
row another session had committed during its window back to that session's
|
||||
BEGIN-time value, seen in production as claims reverting minutes after they
|
||||
were made. The Dolt commit now runs after the SQL transaction commits, against
|
||||
the post-merge working set. Its failure is logged rather than returned: the
|
||||
data is durably committed by then and rides the next Dolt commit, and treating
|
||||
an applied mutation as failed is what made retries double-apply and claim
|
||||
verification disown claims the caller held. Reported and fixed by
|
||||
@nova-submodules.
|
||||
|
||||
- **Removed-backend rejection now detects an existing Dolt database** and gives
|
||||
the exact `metadata.json` heal (change `"backend"` to `"dolt"`, or delete the
|
||||
field) instead of a destructive export/reinitialize path. Workspaces that bd
|
||||
v1.2.x opened as Dolt despite a stale `"backend"` value are one edit from
|
||||
healthy, and the message now says so. Rejection remains fail-closed and
|
||||
read-only — no storage database is opened or modified — and still exits 1.
|
||||
(Detection helper ported from @steveyegge's #4740.)
|
||||
|
||||
- `bd migrate` no longer aborts with a duplicate-primary-key error when the same
|
||||
dependency edge exists in two typed target columns; duplicate edges are now
|
||||
merged deterministically (issue-ref wins over wisp/external), renaming an issue
|
||||
no longer leaves its dependency rows on a stale primary key, and databases left
|
||||
half-rekeyed by earlier binaries are detected and repaired on the next
|
||||
migration pass (#5268).
|
||||
|
||||
- **Legacy tracked `ignored_schema_migrations` self-heals** by untracking it at
|
||||
open time, unwedging `bd dolt pull` on upgraded databases (#4356).
|
||||
|
||||
- **A v1.1.x/v1.2.x ignored-migration cursor is believed** when
|
||||
`leases.granted_node` is merely not yet migrated, so upgrades apply only the
|
||||
pending ignored tail instead of replaying `ignored/0007` and silently
|
||||
restamping `wisps.updated_at` (#5981 class, #5366 follow-up).
|
||||
|
||||
- **Auto-export heals after `bd delete` instead of permanently refusing** — the
|
||||
orphan guard proves deletions against the store's own history (embedded and
|
||||
server modes), stores wedged by earlier binaries recover on first run, and
|
||||
`export-state.json` is now versioned (#5896).
|
||||
|
||||
- **`bd flatten` and `bd compact` now finish with a full Dolt GC** (all
|
||||
generations), so re-running them on a previously-GC'd store actually reclaims
|
||||
the orphaned history and retires orphaned `--as-of` addresses; `bd gc` gains
|
||||
`--full` and hints when a default pass reclaims little (#5907).
|
||||
|
||||
- **`--storage-class` is honored on the proxied-server and `--file` routes** and
|
||||
rejected as a plan-wide `--graph` flag; it was silently ignored there.
|
||||
|
||||
- **Delete and cascade `dep_remove` journal rows are attributed to the
|
||||
requesting actor** (#5985); `bd events export`/`tail` now say when the journal
|
||||
is disabled.
|
||||
|
||||
- **Truthful errors when a server-scoped credential cannot reach the requested
|
||||
database** (missing / denied / wrong-session attribution); `--init-if-missing`
|
||||
is honored in proxied-server mode.
|
||||
|
||||
- **The aux row re-key survives dolt#11131-class encoding drift** instead of
|
||||
failing mid-upgrade with a raw `invalid hash length` error. Drifted tables are
|
||||
skipped with a warning, recorded clone-locally in `aux_row_rekey_drifted`, and
|
||||
re-keyed on a later pass, rather than leaving the database unopenable. This
|
||||
already reached 1.1.x and v1.2.2 users — it is the [1.1.2] fix — and lands on
|
||||
the main line here, so a store upgrading from v1.2.2 is not newly exposed
|
||||
(#5064, #4380). Diagnosis and fix by @marcodelpin, carried and reworked by
|
||||
@maphew.
|
||||
|
||||
- **Server mode honors `Config.LenientOpen`**, so the dirty-table guard's
|
||||
documented recovery is executable. The refusal tells you to run
|
||||
`bd dolt commit` / `bd vc commit`, but against an external Dolt server those
|
||||
commands could not open the store to do it — the flag reached server mode and
|
||||
`newServerMode` never read it, while the field's own doc comment said "Ignored
|
||||
in server mode". That left the #4566 deadlock intact for exactly the case with
|
||||
no way out: embedded mode can move the database directory aside and
|
||||
`bd bootstrap`, and there is no equivalent against a shared server. Fixed by
|
||||
@Toady00 (#5783, #5781).
|
||||
|
||||
- **`bd bootstrap` probes git remotes for Dolt data instead of rejecting them
|
||||
outright** (#6037, #5743, #5663). `bd init` deliberately persists a
|
||||
git-origin-derived `sync.remote` into the tracked `.beads/config.yaml` — a git
|
||||
origin is a valid Dolt remote before `refs/dolt/data` exists, because the first
|
||||
`bd dolt push` creates that ref on the same remote — but bootstrap classified
|
||||
those URLs as code-repo URLs and returned before the origin auto-detect that
|
||||
would have hydrated the clone, `git+https://` and `git+ssh://` included.
|
||||
Committed `sync.remote` values from earlier releases hydrate again. The failure
|
||||
was silent because one outcome code covered both "a database already exists,
|
||||
nothing to do" and "I refused and left you with nothing": bootstrap printed
|
||||
`✓ Database already exists`, exited 0, and created nothing, after which
|
||||
`bd init --reinit-local` pointed back at `bd bootstrap` in a closed loop.
|
||||
Bootstrap now exits non-zero whenever it declines to set up a database.
|
||||
|
||||
- **`--set-metadata` again stores numbers/booleans/null as typed JSON scalars**
|
||||
(v1.2.2 behavior); string-forcing lives on `--metadata-json`. Values written by
|
||||
in-window dev builds are left as strings; re-apply the flag to retype a key.
|
||||
|
||||
- **`bd create --json` (and `POST /v0/beads/issues`) again echo sub-second
|
||||
RFC3339Nano timestamps**; reads (`show`/`list`) remain second-precision as in
|
||||
v1.2.2.
|
||||
|
||||
- **`bd purge` and `bd prune` select candidates by TIER, so a typed wisp is
|
||||
ephemeral however it was minted**
|
||||
([#5995](https://github.com/gastownhall/beads/pull/5995)). The two sweeps
|
||||
split the world between them — `bd purge` clears the ephemeral tier, `bd
|
||||
prune` the durable one — but membership was decided by the raw `ephemeral`
|
||||
column, and a wisp minted before that column was set carried a `wisp_type`
|
||||
with `ephemeral = 0`. Such a bead belonged to neither sweep: `bd purge`
|
||||
reported "No closed ephemeral beads to purge" while `bd prune` skipped it as
|
||||
a wisp. One production database had 858 such rows / 7.3 MB that no sweep
|
||||
could ever reach. The tiers are now complementary predicates over both
|
||||
columns — ephemeral is `ephemeral = 1 OR wisp_type` is non-empty, durable is
|
||||
its exact complement — evaluated across both planes rather than taking the
|
||||
wisps-plane fast path, because legacy typed wisps live in the `issues` table.
|
||||
A non-empty `wisp_type` now also implies ephemeral at mint, on every create
|
||||
path, so no new bead can land in the gap. **A previously unreachable typed
|
||||
wisp is now a `bd purge` candidate**, so the first purge after upgrade may
|
||||
clear considerably more than usual. NoHistory beads (wisps plane, no
|
||||
`wisp_type`) stay durable-tier, unchanged.
|
||||
|
||||
- **`bd prime` says when it could NOT read the memory plane**
|
||||
([#5877](https://github.com/gastownhall/beads/issues/5877)). A broken or
|
||||
unreachable store made prime omit the memory section entirely, so a session
|
||||
|
|
@ -246,9 +706,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|||
`EmbeddedDoltStore` implements neither `DiffStore` nor `StateHasher`, so in
|
||||
the default embedded mode the incremental path is inert (`incremental
|
||||
skipped — store does not implement DiffStore`) and every cycle is still a
|
||||
full export. The deletion-proof guard below is likewise server-mode only, so
|
||||
[#5896](https://github.com/gastownhall/beads/issues/5896) stays open for
|
||||
embedded mode, where `bd delete` still wedges auto-export.
|
||||
full export. The deletion-proof guard below started out server-mode only for
|
||||
the same reason; [#5896](https://github.com/gastownhall/beads/issues/5896) is
|
||||
now closed for embedded mode too — see the store-history heal entry below.
|
||||
|
||||
**Caveat: the diff anchor only advances on real commits.** In server mode
|
||||
dolt auto-commit is off, so with no commits being made the anchor stays put
|
||||
|
|
@ -388,8 +848,67 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|||
`ParentID`. Programmatic callers that set them got unfiltered results back and
|
||||
no error — a full list where a scoped one was asked for.
|
||||
|
||||
<!-- PROVISIONAL: the four entries below are the proposed changelog lines from
|
||||
#6055 and #6056, which were still OPEN when this rollup was written.
|
||||
The RC is gated on both merging, so this fence comes off at RC-prep time:
|
||||
drop these two comment lines once they have landed, or delete the whole
|
||||
block (entries included) if either PR does not land. -->
|
||||
|
||||
- Proxied-server mode (and `bd serve`) ran schema migrations on every store
|
||||
open without consulting any migration gate, so an upgraded client silently
|
||||
migrated a shared database — including from read-only commands. The gate now
|
||||
runs on that path too: read commands warn and continue on the current
|
||||
schema, writes refuse, and `bd serve` fails to start until the schema is
|
||||
reconciled. (#5043)
|
||||
|
||||
- `bd migrate schema` now works in proxied-server mode instead of refusing.
|
||||
The migration runs during the provider open under the verb's consent. (#5043)
|
||||
|
||||
- Migration-gate and schema-skew failures on the proxied open path and at
|
||||
`bd serve` startup now print their full actionable block instead of a
|
||||
single truncated line. (#5043)
|
||||
|
||||
- **`bd doctor` now honors strict `--readonly` and the migration freeze**
|
||||
(#6028). `bd doctor --fix` / `--clean` refuse to mutate under either gate —
|
||||
the freeze refusal exits 14 and names the marker, and there is no doctor-side
|
||||
override — and plain `bd doctor` diagnosis no longer rewrites `.local_version`
|
||||
or auto-applies schema migrations while a freeze is active or `--readonly` is
|
||||
set; it reports the pending migration instead. Both gates key on the directory
|
||||
doctor was pointed at, not just the one it was launched in. Diagnosis itself
|
||||
keeps working under a freeze.
|
||||
|
||||
<!-- END PROVISIONAL -->
|
||||
|
||||
### Security
|
||||
|
||||
- **Release binaries now build with Go 1.26.7** instead of 1.26.5, closing seven
|
||||
standard-library advisories reachable from `bd`: quadratic `net/url` path
|
||||
resolution, `html/template` JavaScript-regexp context tracking, unbounded
|
||||
post-handshake `crypto/tls` messages, a missing `ReadHeaderTimeout` on
|
||||
`net/http`'s unencrypted HTTP/2 check, unbounded recursion in `encoding/xml`
|
||||
and `encoding/asn1`, and the `x/net/idna` Punycode bug in `net/http`'s
|
||||
vendored copy. `bd serve` and bd's outbound TLS calls exercise these paths.
|
||||
The `go` directive stays at 1.26.5, so nothing changes for code importing the
|
||||
beads module.
|
||||
|
||||
- **Dependency bumps clearing all 25 open advisories.** `golang.org/x/crypto`
|
||||
0.55.0, `golang.org/x/mod` 0.40.0, `klauspost/compress` 1.18.7,
|
||||
`moby/go-archive` 0.3.3, `kin-openapi` 0.144.0 with `oapi-codegen` 2.7.1, and
|
||||
a refreshed `integrations/beads-mcp/uv.lock`. None of the fixed code was
|
||||
reachable from the shipped `bd` binary: the go-archive and x/crypto/ssh paths
|
||||
are testcontainers-only, the compress bug is in the `s2` codec bd does not
|
||||
link, and the kin-openapi critical is in `openapi3filter` middleware that
|
||||
enters the graph only through the `tool` directive for spec codegen. No
|
||||
behavior change; no dolt bump was required.
|
||||
|
||||
### Documentation
|
||||
|
||||
- **Known limitation: multi-rig prefix routing (`routes.jsonl`) is not
|
||||
supported with proxied-server rigs** — cross-rig bead gates stay pending,
|
||||
`bd close` of a bead gate in proxied-server mode requires `bd gate check`
|
||||
or `--force`, and routed lookups cannot open proxied-server targets
|
||||
(#5861).
|
||||
|
||||
- **The heartbeat/re-home invariant and the two states it can strand are now
|
||||
documented where the code lives** (wy-sp2l4): a heartbeat proves the holder
|
||||
is alive, not that the lease moved, so `granted_node` is backfilled but never
|
||||
|
|
@ -432,53 +951,6 @@ stopgap (`BD_IGNORE_SCHEMA_SKEW=1`).
|
|||
`go install github.com/steveyegge/beads/cmd/bd@latest` resolves to this
|
||||
release instead of the accidental one. (The retract block is also
|
||||
carried on main so future tags keep the retractions.)
|
||||
- **`sort` on `GET /v0/beads/issues`.** The listing served one order —
|
||||
`(created_at DESC, id ASC)` — because the cursor is a keyset position in it,
|
||||
and the spec said so in its own words: "the sort order is welded to the cursor
|
||||
contract, and a new order needs new surface." The cost of that welding fell on
|
||||
every client that wanted `bd list`'s ordering, because the only way to get it
|
||||
was to page the whole result set and re-sort locally. Measured over a
|
||||
1400-row store at the 200-row page an HTTP client actually uses, that is
|
||||
**7 requests plus a client-side comparator; `?sort=priority` is 1**
|
||||
(`TestProxiedServerListSortRetiresTheWalk`, which runs both strategies against
|
||||
a real `bd serve` and checks both against `bd list --json` row for row). It is
|
||||
the one cost on this surface that got worse as a project grew.
|
||||
|
||||
**Two values, and the set is closed.** `created` is the existing order, now
|
||||
spellable. `priority` is `(priority ASC, created_at DESC, id ASC)` — `bd
|
||||
list`'s flagless ordering, which is also what `bd list --sort priority`
|
||||
produces, so one served order retires the walk for both. The other seven
|
||||
orders `bd list --sort` takes are not offered: each value here is a cursor
|
||||
contract needing a key proven total, and `id` is a natural-numeric order no
|
||||
database expresses, `updated` moves on every write, `closed` is nullable, and
|
||||
`status`/`title`/`type`/`assignee` are mutable and unindexed.
|
||||
|
||||
**Absent `sort` still means `created`, permanently.** It is the compatibility
|
||||
contract for every client written before the parameter existed; changing it
|
||||
would alter which rows a truncated page contains, with no error to notice it
|
||||
by. A server that predates the parameter answers `param: "sort"` with
|
||||
`reason: "unknown_parameter"`, which is the per-parameter capability probe a
|
||||
client dispatches on to fall back.
|
||||
|
||||
**The cursor now carries its order, and a mismatch is refused.** This is the
|
||||
half that makes the parameter safe rather than merely useful. The token was
|
||||
base64 of `{t,i}` with no binding, so a `created`-order cursor replayed under
|
||||
`sort=priority` would have decoded perfectly and been read as a position in a
|
||||
different total order — a page that both skips and duplicates rows, served
|
||||
with a 200, undetectable by the client. Tokens are now `v2` with an explicit
|
||||
order member and decode refuses any token whose order differs from the
|
||||
request's, as `invalid_cursor` (documented recovery: restart paging).
|
||||
Outstanding `v1` tokens stay readable as the `created`-order positions they
|
||||
are, so **no traversal in flight has to restart**. This does not contradict
|
||||
"the token carries no filters": filters select the set, the order decides what
|
||||
the position means.
|
||||
|
||||
**`priority` is a mutable key**, which `created_at` is not, and the spec says
|
||||
so: under `created` only new rows move relative to a walk, while a priority
|
||||
update moves an existing row too, so it can be seen twice or missed. That is
|
||||
the already-documented "a cursor pins a position, not a snapshot" caveat
|
||||
reached by a second route, not a new class of error — unchanged data never
|
||||
skips or repeats under either order.
|
||||
|
||||
## [1.2.1] - 2026-08-11
|
||||
|
||||
|
|
|
|||
398
RELEASING.md
398
RELEASING.md
|
|
@ -6,13 +6,16 @@ This document describes the complete release process for beads, including GitHub
|
|||
|
||||
- [Overview](#overview)
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Release Branches](#release-branches)
|
||||
- [Release Checklist](#release-checklist)
|
||||
- [1. Prepare Release](#1-prepare-release)
|
||||
- [2. GitHub Release](#2-github-release)
|
||||
- [3. Homebrew Update](#3-homebrew-update)
|
||||
- [4. PyPI Release (MCP Server)](#4-pypi-release-mcp-server)
|
||||
- [5. npm Package Release](#5-npm-package-release)
|
||||
- [6. Verify Release](#6-verify-release)
|
||||
- [5. Plugin Marketplace Update](#5-plugin-marketplace-update)
|
||||
- [6. npm Package Release](#6-npm-package-release)
|
||||
- [7. Verify Release](#7-verify-release)
|
||||
- [Version Numbering](#version-numbering)
|
||||
- [Prerelease / Release Candidate (RC) Workflow](#prerelease--release-candidate-rc-workflow)
|
||||
- [Hotfix Releases](#hotfix-releases)
|
||||
- [Rollback Procedure](#rollback-procedure)
|
||||
|
|
@ -28,17 +31,21 @@ A beads release involves multiple distribution channels:
|
|||
|
||||
### The Easy Way (Recommended)
|
||||
|
||||
For routine releases, use the fully automated release script:
|
||||
For routine releases, run the release molecule:
|
||||
|
||||
```bash
|
||||
./scripts/release.sh 0.22.0
|
||||
bd mol wisp beads-release --var version=1.3.0
|
||||
```
|
||||
|
||||
This handles version bump, tests, git tag, Homebrew update, and local
|
||||
installation in one shot. See [scripts/README.md](scripts/README.md#releasesh--the-easy-button)
|
||||
for details. The rest of this document is the manual / step-by-step process,
|
||||
useful for understanding what `release.sh` does and for handling edge cases
|
||||
(hotfixes, rollbacks, manual PyPI/npm publishes).
|
||||
`.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
|
||||
|
||||
|
|
@ -79,21 +86,105 @@ 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:
|
||||
|
||||
```bash
|
||||
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](#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:
|
||||
|
||||
```bash
|
||||
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](#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](engdocs/RELEASE-STABILITY-GATE.md)
|
||||
- [ ] **Regression tests pass** (`make test-regression`)
|
||||
- [ ] **Every release target cross-compiles** — see
|
||||
[Cross-compile before tagging](#cross-compile-before-tagging). PR CI does
|
||||
not build them ([#5662](https://github.com/gastownhall/beads/issues/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)](#documentation-site-mintlify).
|
||||
- [ ] `./scripts/check-versions.sh` passes
|
||||
- [ ] No uncommitted changes
|
||||
- [ ] On `main` branch and up to date with origin
|
||||
- [ ] 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](https://github.com/gastownhall/beads/pull/5661) fixed the break,
|
||||
[#5662](https://github.com/gastownhall/beads/issues/5662) tracks the CI gap).
|
||||
Until that gap is closed, build them by hand before tagging:
|
||||
|
||||
```bash
|
||||
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](#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.**
|
||||
|
|
@ -117,58 +208,86 @@ Add release notes to CHANGELOG.md:
|
|||
- Changed behavior of B (migration guide)
|
||||
```
|
||||
|
||||
Commit the CHANGELOG changes:
|
||||
Commit the CHANGELOG changes and open a PR against the release branch:
|
||||
|
||||
```bash
|
||||
git add CHANGELOG.md
|
||||
git commit -m "docs: Add CHANGELOG entry for v0.22.0"
|
||||
git push origin main
|
||||
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
|
||||
|
||||
Use the version bump script to update all version references and create the 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.)
|
||||
|
||||
```bash
|
||||
# Dry run - shows what will change
|
||||
./scripts/bump-version.sh 0.22.0
|
||||
|
||||
# Full release with all local installations
|
||||
./scripts/bump-version.sh 0.22.0 --commit --tag --push --all
|
||||
./scripts/update-versions.sh 0.22.0
|
||||
./scripts/check-versions.sh # must pass before you commit
|
||||
```
|
||||
|
||||
**Available flags:**
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--commit` | Create a git commit with version changes |
|
||||
| `--tag` | Create annotated git tag (requires --commit) |
|
||||
| `--push` | Push commit and tag to origin (requires --tag) |
|
||||
| `--install` | Build and install bd to `~/go/bin` AND `~/.local/bin` |
|
||||
| `--mcp-local` | Install beads-mcp from local source via uv/pip |
|
||||
| `--upgrade-mcp` | Upgrade beads-mcp from PyPI (after PyPI publish) |
|
||||
| `--restart-servers` | Restart all Dolt servers to pick up new version |
|
||||
| `--all` | Shorthand for `--install --mcp-local --restart-servers` |
|
||||
|
||||
This updates:
|
||||
- `cmd/bd/version.go` - CLI version constant
|
||||
- `integrations/beads-mcp/pyproject.toml` - MCP server version
|
||||
- `integrations/beads-mcp/src/beads_mcp/__init__.py` - MCP Python version
|
||||
- `plugins/beads/.claude-plugin/plugin.json` - Claude plugin version
|
||||
- `plugins/beads/.codex-plugin/plugin.json` - Codex plugin version
|
||||
- `.claude-plugin/marketplace.json` - Claude marketplace version
|
||||
- `npm-package/package.json` - npm package version
|
||||
- `cmd/bd/templates/hooks/*` - Git hook versions
|
||||
- `README.md` - Documentation version
|
||||
- `PLUGIN.md` - Version requirements
|
||||
- `CHANGELOG.md` - Creates release entry from [Unreleased]
|
||||
- `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
|
||||
|
||||
The `--commit --tag --push` flags will:
|
||||
1. Create a git commit with all version changes
|
||||
2. Create an annotated tag `v0.22.0`
|
||||
3. Push both commit and tag to origin
|
||||
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.
|
||||
|
||||
This triggers GitHub Actions to build release artifacts automatically.
|
||||
Then commit and land it as a PR — **not** a direct push, and **do not tag
|
||||
yet**:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
|
|
@ -186,12 +305,14 @@ release.
|
|||
```bash
|
||||
# 1. Update CHANGELOG.md and cmd/bd/info.go with release notes (manual step)
|
||||
|
||||
# 2. Bump version and install everything locally
|
||||
./scripts/bump-version.sh 0.22.0 --commit --all
|
||||
# 2. Bump versions and verify
|
||||
./scripts/update-versions.sh 0.22.0
|
||||
./scripts/check-versions.sh
|
||||
|
||||
# 3. Test locally, then tag and push
|
||||
# 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 main
|
||||
git push origin v0.22.0
|
||||
```
|
||||
|
||||
|
|
@ -199,18 +320,6 @@ 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.
|
||||
|
||||
**Alternative (step-by-step):**
|
||||
|
||||
```bash
|
||||
# Just commit
|
||||
./scripts/bump-version.sh 0.22.0 --commit
|
||||
|
||||
# Then manually tag and push
|
||||
git tag -a v0.22.0 -m "Release v0.22.0"
|
||||
git push origin main
|
||||
git push origin v0.22.0
|
||||
```
|
||||
|
||||
## 2. GitHub Release
|
||||
|
||||
### Using GoReleaser (Recommended)
|
||||
|
|
@ -383,19 +492,33 @@ 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:
|
||||
|
||||
```bash
|
||||
# After tagging (see "Update Version and Create Release Tag" above):
|
||||
# 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"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
The pin bump lands on `main`, since that is where Mintlify deploys from — fold
|
||||
it into the forward-port PR described in [Release Branches](#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:
|
||||
|
||||
```bash
|
||||
rg 'These docs are for the' docs/index.md
|
||||
```
|
||||
|
||||
## 6. npm Package Release
|
||||
|
||||
The npm package wraps the native binary for Node.js environments.
|
||||
|
|
@ -416,7 +539,7 @@ npm org ls beads
|
|||
# Navigate to npm package
|
||||
cd npm-package
|
||||
|
||||
# Version should already be updated by bump-version.sh
|
||||
# Version should already be updated by update-versions.sh
|
||||
cat package.json | grep version
|
||||
|
||||
# Run all tests
|
||||
|
|
@ -525,14 +648,32 @@ curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/inst
|
|||
bd version
|
||||
```
|
||||
|
||||
### CLI Docs Pin
|
||||
### Docs Cutover
|
||||
|
||||
```bash
|
||||
cat docs/cli-docs.pin # should be the tag just released, not an older one
|
||||
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 it's stale, do the bump from the "Documentation Site (Mintlify)" step
|
||||
above before calling the release done.
|
||||
If either is stale, do the bump from the
|
||||
[Documentation Site (Mintlify)](#documentation-site-mintlify) step above
|
||||
before calling the release done.
|
||||
|
||||
### Release Notes Rollup
|
||||
|
||||
```bash
|
||||
# [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:
|
||||
|
||||
```bash
|
||||
git merge-base --is-ancestor <commit> <previous-tag> && echo "in the tag" || echo "MISFILED"
|
||||
```
|
||||
|
||||
## Prerelease / Release Candidate (RC) Workflow
|
||||
|
||||
|
|
@ -556,32 +697,42 @@ identifier (e.g. `1.1.0-rc.1`); Python tooling normalizes this to PEP 440 form
|
|||
|
||||
### 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](#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`.
|
||||
|
||||
```bash
|
||||
# 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,
|
||||
# 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.
|
||||
# prerelease suffix the same way at build time, and check-versions.sh
|
||||
# checks those fields against the base version for exactly this reason.
|
||||
|
||||
# 3. Keep the MCP lockfile in sync (PEP 440 normalizes to 1.1.0rc1), or the
|
||||
# Package Gate (MCP) check goes red:
|
||||
(cd integrations/beads-mcp && uv lock)
|
||||
|
||||
# 4. Validate locally.
|
||||
# 3. Validate locally.
|
||||
./scripts/check-versions.sh
|
||||
|
||||
# 5. Open a PR for the RC prep and have it reviewed. RC prep should land
|
||||
# through normal review, not auto-merge.
|
||||
# 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 is merged to `main`, cut the tag from the merge commit:
|
||||
After the RC prep merges, cut the tag from the merged commit on the release
|
||||
branch:
|
||||
|
||||
```bash
|
||||
git checkout main && git pull
|
||||
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
|
||||
```
|
||||
|
|
@ -595,36 +746,36 @@ above. Tag creation is restricted to release maintainers; see
|
|||
- 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`). The stable release **does** publish
|
||||
to Homebrew/PyPI/npm, so follow the standard
|
||||
(`./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](#1-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](#release-branches).
|
||||
|
||||
```bash
|
||||
# Create hotfix branch from tag
|
||||
git checkout -b hotfix/v0.22.1 v0.22.0
|
||||
# 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
|
||||
|
||||
# Make fixes
|
||||
# ... edit files ...
|
||||
|
||||
# Bump version to 0.22.1
|
||||
./scripts/bump-version.sh 0.22.1 --commit
|
||||
# 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 hotfix/v0.22.1
|
||||
git push origin release/0.22.1
|
||||
git push origin v0.22.1
|
||||
|
||||
# Follow normal release process
|
||||
goreleaser release --clean
|
||||
|
||||
# Merge back to main
|
||||
git checkout main
|
||||
git merge hotfix/v0.22.1
|
||||
git push origin main
|
||||
# Forward-port the fix AND the version bump to main
|
||||
git log --oneline main..release/0.22.1
|
||||
```
|
||||
|
||||
## Rollback Procedure
|
||||
|
|
@ -715,13 +866,10 @@ After a successful release:
|
|||
|
||||
1. **Upgrade local beads-mcp installation** to the new version:
|
||||
```bash
|
||||
# Option 1: Use the bump-version.sh script (recommended during version bump)
|
||||
./scripts/bump-version.sh <version> --upgrade-mcp
|
||||
|
||||
# Option 2: Manual upgrade via pip (if installed globally)
|
||||
# If installed globally
|
||||
pip install --upgrade beads-mcp
|
||||
|
||||
# Option 3: Manual upgrade via uv tool (if installed as a tool)
|
||||
# If installed as a uv tool
|
||||
uv tool upgrade beads-mcp
|
||||
|
||||
# Verify the new version
|
||||
|
|
@ -731,20 +879,17 @@ After a successful release:
|
|||
# The MCP server will load the newly installed version
|
||||
```
|
||||
|
||||
**Note:** The `--upgrade-mcp` flag can be combined with other flags:
|
||||
```bash
|
||||
# Update versions, commit, install bd binary, and upgrade beads-mcp all at once
|
||||
./scripts/bump-version.sh 0.24.3 --commit --install --upgrade-mcp
|
||||
```
|
||||
2. **Forward-port the release branch to `main`** — see
|
||||
[Release Branches](#release-branches). Include the `docs/cli-docs.pin` bump
|
||||
and the `docs/index.md` release line.
|
||||
|
||||
2. **Verify the upgraded CLI**:
|
||||
3. **Verify the upgraded CLI**:
|
||||
```bash
|
||||
bd version
|
||||
bd doctor quick
|
||||
```
|
||||
|
||||
3. **Announce** on relevant channels (Twitter, blog, etc.)
|
||||
4. **Update documentation** if needed
|
||||
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
|
||||
|
|
@ -793,13 +938,38 @@ goreleaser build --snapshot --clean
|
|||
|
||||
Beads follows [Semantic Versioning](https://semver.org/):
|
||||
|
||||
- **MAJOR** (x.0.0): Breaking changes
|
||||
- **MINOR** (0.x.0): New features, backwards compatible
|
||||
- **PATCH** (0.0.x): Bug fixes, backwards compatible
|
||||
- **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,
|
||||
|
|
|
|||
|
|
@ -220,6 +220,26 @@ type VersionChange struct {
|
|||
|
||||
// versionChanges contains agent-actionable changes for recent versions
|
||||
var versionChanges = []VersionChange{
|
||||
{
|
||||
Version: "1.3.0",
|
||||
Date: "2026-08-28",
|
||||
Changes: []string{
|
||||
"RELEASE: first tested release off main since the 1.1 line. v1.2.2 shipped the v1.1.2 tree, so a v1.2.2 user gets the 1.2.1 changes AND the 1.3.0 changes in one step; read the [1.3.0] AND [1.2.1] sections of CHANGELOG.md. 'bd upgrade review' prints exactly the entries between your previous version and this one — prefer it to 'bd info --whats-new', which dumps the whole release history.",
|
||||
"MIGRATION: on an embedded/local store the first invocation auto-migrates from schema v53 to v66 in place. That is ~28 migrations, not 13: the main series runs 0054->0066, then the clone-local series runs 0012->0026 through the same printer, so the counter VISIBLY RESTARTS partway through. That is not a loop — let it finish. Two passes rewrite rows, so the first command is noticeably slower; it is crash-resumable, do not interrupt it. Progress prints per step on stderr only when stderr is a terminal — a silent CI upgrade is not a stuck one.",
|
||||
"SHARED SERVER: a shared Dolt sql-server is NEVER auto-migrated (#5920, #6048) — migrating promotes the schema for every connected client at once, so it waits for explicit consent via 'bd migrate schema' (add --global for the shared global database). Upgrade every client of that server FIRST; between upgrade and consent, upgraded clients read normally and their writes are refused with guidance. If the shared server also has a Dolt remote, use 'bd migrate --force' from exactly one machine, then 'bd dolt push'.",
|
||||
"BACKUP: back up BEFORE installing, with your OLD binary. Under 1.3.0 'bd export' triggers the migration before exporting, so a snapshot taken afterwards cannot protect you against the migration going wrong. Old binary: 'bd dolt push' (remote-backed stores) then 'bd export --all -o .beads/backup/pre-1.3.0.jsonl'. For a Dolt-native snapshot use 'bd backup init <path>' then 'bd backup sync' — bare 'bd backup' is a command group that prints help and takes NO backup. Remote-backed stores stay gated after install; one designated clone migrates and pushes.",
|
||||
"UPGRADE: after migrating, older co-resident binaries REFUSE the store (forward schema-skew guard), so every client sharing a store must be upgraded together. Check with 'which -a bd' and restart any long-running 'bd serve'. Rollback is a schema-cursor rollback: https://beads.gascity.com/recovery/accidental-1-2-1-release",
|
||||
"BREAKING (highlights, not the full set — read the [1.2.1] CHANGELOG section too): 'bd update -s <done-status>' enforces close policy (override with --force); 'bd search' includes closed by default (narrow with --status open); the no-ID last-touched fallback on update/close is interactive-only; 'bd human list' hides done/frozen/pinned and validates --status; 'bd dolt push'/'bd sync' no longer adopt a git-origin-derived Dolt remote without consent; an explicitly configured Dolt port outranks BEADS_DOLT_PORT; and actor matching decodes an exact '--' run to '/'.",
|
||||
"BREAKING: 'bd --readonly serve' is now REFUSED instead of binding a writable server, so a scripted read-only server does not come back up after this upgrade — drop the flag. 'bd config list' and GET /v0/beads/config no longer enumerate the kv. plane where 'bd remember' memories live (use 'bd kv'/'bd remember'; scripts get empty output, not an error). The published backend package drops OrphanHandling and issueops.CheckOrphan, so a Go consumer naming them no longer compiles.",
|
||||
"BREAKING: the CPU profiling flag is now --cpu-profile; the old --profile spelling is gone with no alias and fails as an unknown flag.",
|
||||
"CHANGE: migration 0061 rekeys every events/comments/snapshot/compaction-snapshot row to a content-derived (UUIDv5-over-SHA-256) id, once per clone, on the first open after upgrade. Ids captured before the upgrade will not resolve afterwards.",
|
||||
"CHANGE: migration 0062 moves the events audit table to the clone-local plane — events keep full local durability and 'bd history <id> --events' still reads them, but they no longer replicate on push or pull.",
|
||||
"CHANGE: the interactions.jsonl audit sidecar is opt-in (audit.enabled defaults false, or BD_AUDIT_ENABLED=1); use 'bd history <id> --events' instead. Auto-backup now defaults OFF under a Dolt sql-server (embedded is unchanged); set backup.enabled explicitly to override.",
|
||||
"CHANGE: 'bd import' now ERRORS on a redirected stdin with no source argument instead of importing the default JSONL — use 'bd import -' or name the file. 'bd hooks install --chain/--force' are accepted no-ops; marker sections always preserve non-bd hook content.",
|
||||
"FIX: 'bd purge'/'bd prune' select candidates by tier (#5995), so typed wisps minted before the ephemeral column are reachable again — the first purge after upgrade may clear considerably more than usual.",
|
||||
"NEW: a two-level cooperative gate writes *.gate.lock files beside .beads and beside the Dolt physical root (e.g. .beads/embeddeddolt.gate.lock). They are flock names, never deleted; 'bd doctor --fix' adds the *.gate.lock* gitignore pattern.",
|
||||
},
|
||||
},
|
||||
{
|
||||
Version: "1.2.2",
|
||||
Date: "2026-08-15",
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ import (
|
|||
|
||||
var (
|
||||
// Version is the current version of bd (overridden by ldflags at build time)
|
||||
Version = "1.2.2"
|
||||
Version = "1.3.0"
|
||||
// Build can be set via ldflags at compile time
|
||||
Build = "dev"
|
||||
// Commit and branch the git revision the binary was built from (optional ldflag)
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
<assemblyIdentity
|
||||
type="win32"
|
||||
name="beads.bd"
|
||||
version="1.2.2.0"
|
||||
version="1.3.0.0"
|
||||
processorArchitecture="*"/>
|
||||
<description>beads - AI-supervised issue tracker</description>
|
||||
<compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
|
||||
|
|
|
|||
|
|
@ -9,8 +9,8 @@
|
|||
"#1": {
|
||||
"0000": {
|
||||
"fixed": {
|
||||
"file_version": "1.2.2",
|
||||
"product_version": "1.2.2",
|
||||
"file_version": "1.3.0",
|
||||
"product_version": "1.3.0",
|
||||
"type": "App"
|
||||
},
|
||||
"info": {
|
||||
|
|
@ -18,12 +18,12 @@
|
|||
"Comments": "AI-supervised issue tracker for coding workflows",
|
||||
"CompanyName": "Steve Yegge",
|
||||
"FileDescription": "beads - AI-supervised issue tracker",
|
||||
"FileVersion": "1.2.2",
|
||||
"FileVersion": "1.3.0",
|
||||
"InternalName": "bd",
|
||||
"LegalCopyright": "Copyright (c) 2024-2026 Steve Yegge. MIT License.",
|
||||
"OriginalFilename": "bd.exe",
|
||||
"ProductName": "beads",
|
||||
"ProductVersion": "1.2.2"
|
||||
"ProductVersion": "1.3.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@
|
|||
}:
|
||||
buildGoModule {
|
||||
pname = "beads";
|
||||
version = "1.2.2";
|
||||
version = "1.3.0";
|
||||
|
||||
src = self;
|
||||
|
||||
|
|
|
|||
|
|
@ -11,9 +11,12 @@ How to upgrade bd and keep your projects in sync.
|
|||
# Current version
|
||||
bd version
|
||||
|
||||
# What's new in recent versions
|
||||
# What changed since the version you were running — the delta, not the archive
|
||||
bd upgrade review
|
||||
bd upgrade review --json # Machine-readable
|
||||
|
||||
# The full release history (large; every version bd knows about)
|
||||
bd info --whats-new
|
||||
bd info --whats-new --json # Machine-readable
|
||||
```
|
||||
|
||||
## Short Version
|
||||
|
|
@ -22,11 +25,11 @@ bd info --whats-new --json # Machine-readable
|
|||
new binary:
|
||||
`bd dolt push`
|
||||
`bd dolt pull`
|
||||
2. Back up before migration:
|
||||
2. Back up **with that same current binary**, before installing:
|
||||
`bd export --all -o .beads/backup/pre-migrate-$(date +%Y%m%d).jsonl`
|
||||
3. Upgrade using the command that matches your install method.
|
||||
4. After upgrading:
|
||||
`bd info --whats-new`
|
||||
`bd upgrade review`
|
||||
`bd hooks install`
|
||||
`bd version`
|
||||
5. If crossing a schema migration on a remote-backed database, only the
|
||||
|
|
@ -139,6 +142,83 @@ bd migrate
|
|||
bd migrate --yes
|
||||
```
|
||||
|
||||
### Upgrading to 1.3.0
|
||||
|
||||
A 1.2.2 or 1.1.x database sits at schema v53, and 1.3.0 knows v66. That is more
|
||||
than a routine upgrade: 1.2.2 was a recovery release that shipped the 1.1 code
|
||||
under a higher version number, so there is a release line's worth of schema
|
||||
between the two.
|
||||
|
||||
#### Back up first, with the binary you have now
|
||||
|
||||
Do this **before** you install 1.3.0. Under the new binary, `bd export` triggers
|
||||
the migration before it exports, so a snapshot taken afterwards is a
|
||||
post-migration snapshot and cannot protect you against the migration going
|
||||
wrong. The same ordering rule as the section below applies: do all syncing with
|
||||
your **current** binary, since once 1.3.0 is installed the pending-migration
|
||||
gate refuses `bd dolt push` and `bd dolt pull` too.
|
||||
|
||||
```bash
|
||||
# with your CURRENT bd:
|
||||
bd dolt push # remote-backed stores only
|
||||
bd export --all -o .beads/backup/pre-1.3.0-$(date +%Y%m%d).jsonl
|
||||
```
|
||||
|
||||
For a Dolt-native snapshot that keeps history and config, configure a
|
||||
destination and sync it. Bare `bd backup` takes no backup — it is a command
|
||||
group that prints help and exits 0:
|
||||
|
||||
```bash
|
||||
bd backup init <path-or-dolthub-url> # once, to configure a destination
|
||||
bd backup sync # take the snapshot
|
||||
```
|
||||
|
||||
#### What the migration looks like
|
||||
|
||||
On an embedded or local store, the first command you run after installing
|
||||
applies the whole set, in place. (A shared `dolt sql-server` is never
|
||||
auto-migrated — see [Shared servers](#shared-servers) below.) The main series
|
||||
runs 0054 → 0066 (13 migrations), and then the clone-local series runs through
|
||||
the same printer with its own numbering, 0012 → 0026 — so it is about
|
||||
**28 migrations**, and the counter visibly restarts partway through:
|
||||
|
||||
```
|
||||
Applying migration 0065: widen_wisp_comments_text…
|
||||
Applying migration 0066: add_events_journal_actor…
|
||||
Applying migration 0012: create_leases… ← clone-local series, not a restart
|
||||
```
|
||||
|
||||
A counter jumping backwards looks exactly like a loop. It is not one — let it
|
||||
finish. Expect the run to take noticeably longer than the commands after it
|
||||
(two passes rewrite rows rather than reshaping tables). It is crash-resumable
|
||||
and picks up where it left off.
|
||||
|
||||
Those lines go to stderr, and only when stderr is a terminal, so a piped or CI
|
||||
upgrade prints nothing at all. Silence there is not a stall either.
|
||||
|
||||
#### Upgrade every client that shares a store, together
|
||||
|
||||
A bd binary refuses a database migrated past the schema it knows, rather than
|
||||
proceeding blind. One machine upgrading takes the shared store forward and every
|
||||
client still on 1.2.2 stops working. Check for a second binary earlier in your
|
||||
`PATH` with `which -a bd`, and restart any long-running `bd serve` — noting that
|
||||
`bd --readonly serve` is now refused outright, so a server scripted with that
|
||||
flag will not come back up until you drop it.
|
||||
|
||||
If the store is a shared `dolt sql-server` rather than a local one, follow
|
||||
[Shared servers](#shared-servers) below: 1.3.0 will not migrate it without
|
||||
explicit consent, precisely so the fleet upgrade can come first.
|
||||
|
||||
If you need to go back, the rollback is a schema-cursor rollback rather than a
|
||||
downgrade of the data — see
|
||||
[Accidental v1.2.1 Release](/recovery/accidental-1-2-1-release), whose
|
||||
procedure is the same for any cursor rollback even though its worked example is
|
||||
that release.
|
||||
|
||||
Once you are on the new binary, `bd upgrade review` prints exactly the changes
|
||||
between the version you were running and this one. Several commands changed
|
||||
defaults, so read it before your first session.
|
||||
|
||||
### Remote-backed databases and multiple clones
|
||||
|
||||
`bd` refuses to silently apply pending schema migrations to a database that has
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ description: Dependency-aware, Dolt-backed issue tracker built for AI coding age
|
|||
|
||||
**Beads** (`bd`) is a Dolt-powered issue tracker designed for AI-supervised coding workflows.
|
||||
|
||||
These docs are for the 1.1.0 release of beads — see the [v1.1.0 release notes](https://github.com/gastownhall/beads/releases/tag/v1.1.0).
|
||||
These docs are for the 1.3.0 release of beads — see the [v1.3.0 release notes](https://github.com/gastownhall/beads/releases/tag/v1.3.0). Upgrading from 1.2.2 or earlier crosses a schema migration; read [Upgrading](/getting-started/upgrading) first.
|
||||
|
||||
## Why Beads?
|
||||
|
||||
|
|
|
|||
|
|
@ -9,6 +9,7 @@ This section provides step-by-step recovery procedures for common Beads issues.
|
|||
|
||||
| Issue | Symptoms | Runbook |
|
||||
|-------|----------|---------|
|
||||
| Schema Version Mismatch | `bd` refuses with `schema version mismatch: database is at vNN, binary knows up to vNN` | [Accidental v1.2.1 Release](/recovery/accidental-1-2-1-release) |
|
||||
| Init Safety Refusals | `bd init` or `bd dolt` refuses with a pattern code like `pk-fork-refused` | [Recovery Playbooks](/recovery/init-safety) |
|
||||
| Database Corruption | Database errors, missing data | [Database Corruption](/recovery/database-corruption) |
|
||||
| Merge Conflicts | Dolt conflicts during sync | [Merge Conflicts](/recovery/merge-conflicts) |
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
[project]
|
||||
name = "beads-mcp"
|
||||
version = "1.2.2"
|
||||
version = "1.3.0"
|
||||
description = "MCP server for beads issue tracker."
|
||||
readme = "README.md"
|
||||
requires-python = ">=3.10"
|
||||
|
|
|
|||
|
|
@ -4,4 +4,4 @@ This package provides an MCP (Model Context Protocol) server that exposes
|
|||
beads (bd) issue tracker functionality to MCP Clients.
|
||||
"""
|
||||
|
||||
__version__ = "1.2.2"
|
||||
__version__ = "1.3.0"
|
||||
|
|
|
|||
2
integrations/beads-mcp/uv.lock
generated
2
integrations/beads-mcp/uv.lock
generated
|
|
@ -175,7 +175,7 @@ wheels = [
|
|||
|
||||
[[package]]
|
||||
name = "beads-mcp"
|
||||
version = "1.2.2"
|
||||
version = "1.3.0"
|
||||
source = { editable = "." }
|
||||
dependencies = [
|
||||
{ name = "fastmcp" },
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
{
|
||||
"name": "@beads/bd",
|
||||
"version": "1.2.2",
|
||||
"version": "1.3.0",
|
||||
"description": "Beads issue tracker - lightweight memory system for coding agents with native binary support",
|
||||
"main": "bin/bd.js",
|
||||
"bin": {
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
{
|
||||
"name": "beads",
|
||||
"description": "AI-supervised issue tracker for coding workflows. Manage tasks, discover work, and maintain context with simple CLI commands.",
|
||||
"version": "1.2.2",
|
||||
"version": "1.3.0",
|
||||
"author": {
|
||||
"name": "Steve Yegge",
|
||||
"url": "https://github.com/steveyegge"
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
{
|
||||
"name": "beads",
|
||||
"version": "1.2.2",
|
||||
"version": "1.3.0",
|
||||
"description": "AI-supervised issue tracking for coding workflows with agent skills.",
|
||||
"author": {
|
||||
"name": "Steve Yegge",
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
{
|
||||
"name": "beads",
|
||||
"description": "AI-supervised issue tracker for coding workflows. Manage tasks, discover work, and maintain context with simple CLI commands.",
|
||||
"version": "1.2.2",
|
||||
"version": "1.3.0",
|
||||
"author": {
|
||||
"name": "Steve Yegge",
|
||||
"url": "https://github.com/steveyegge"
|
||||
|
|
|
|||
|
|
@ -21,19 +21,28 @@ echo ""
|
|||
|
||||
MISMATCH=0
|
||||
|
||||
check_version() {
|
||||
# Base (prerelease-stripped) form. The Windows PE numeric fields must be purely
|
||||
# numeric, so they carry this rather than $CANONICAL.
|
||||
BASE_VERSION="${CANONICAL%%-*}"
|
||||
|
||||
check_expected() {
|
||||
local _file=$1
|
||||
local version=$2
|
||||
local description=$3
|
||||
local expected=$3
|
||||
local description=$4
|
||||
|
||||
if [ "$version" != "$CANONICAL" ]; then
|
||||
echo -e "${RED}❌ $description: $version (expected $CANONICAL)${NC}"
|
||||
if [ "$version" != "$expected" ]; then
|
||||
echo -e "${RED}❌ $description: ${version:-missing} (expected $expected)${NC}"
|
||||
MISMATCH=1
|
||||
else
|
||||
echo -e "${GREEN}✓ $description: $version${NC}"
|
||||
fi
|
||||
}
|
||||
|
||||
check_version() {
|
||||
check_expected "$1" "$2" "$CANONICAL" "$3"
|
||||
}
|
||||
|
||||
# Check all version files
|
||||
check_version "integrations/beads-mcp/pyproject.toml" \
|
||||
"$(grep '^version = ' integrations/beads-mcp/pyproject.toml 2>/dev/null | sed 's/.*"\(.*\)".*/\1/')" \
|
||||
|
|
@ -51,6 +60,15 @@ check_version "plugins/beads/.codex-plugin/plugin.json" \
|
|||
"$(jq -r '.version' plugins/beads/.codex-plugin/plugin.json 2>/dev/null)" \
|
||||
"Codex plugin.json"
|
||||
|
||||
# update-versions.sh bumps this one too, but it was never gated here — so a
|
||||
# drifted copilot manifest (the same drift class that carried stale .githooks
|
||||
# markers through v1.2.0) would silently no-op the bump's old->new sed, pass
|
||||
# this script, pass the pre-push hook and CI, and ship advertising the previous
|
||||
# version.
|
||||
check_version "plugins/beads/.copilot-plugin/plugin.json" \
|
||||
"$(jq -r '.version' plugins/beads/.copilot-plugin/plugin.json 2>/dev/null)" \
|
||||
"Copilot plugin.json"
|
||||
|
||||
check_version ".claude-plugin/marketplace.json" \
|
||||
"$(jq -r '.plugins[0].version' .claude-plugin/marketplace.json 2>/dev/null)" \
|
||||
"Claude marketplace.json"
|
||||
|
|
@ -107,17 +125,58 @@ for hook in .githooks/*; do
|
|||
done
|
||||
done
|
||||
|
||||
echo ""
|
||||
# Windows PE resource metadata. gen-winres.sh re-derives winres.json's numeric
|
||||
# fields from version.go at build time, so those self-heal — but
|
||||
# manifest.xml's <assemblyIdentity> version is embedded verbatim with no
|
||||
# backstop, and update-versions.sh rewrites both with a sed anchored on the OLD
|
||||
# value, so a drifted file is a silent no-op. Gate them.
|
||||
#
|
||||
# The numeric fields (file_version/product_version, and the manifest's
|
||||
# four-part version) must be purely numeric, so they carry the base version:
|
||||
# for 1.1.0-rc.1 they read 1.1.0 while FileVersion/ProductVersion read the full
|
||||
# prerelease string.
|
||||
WINRES_JSON="cmd/bd/winres/winres.json"
|
||||
for field in file_version product_version; do
|
||||
check_expected "$WINRES_JSON" \
|
||||
"$(jq -r ".RT_VERSION.\"#1\".\"0000\".fixed.$field" "$WINRES_JSON" 2>/dev/null)" \
|
||||
"$BASE_VERSION" "winres.json $field"
|
||||
done
|
||||
for field in FileVersion ProductVersion; do
|
||||
check_expected "$WINRES_JSON" \
|
||||
"$(jq -r ".RT_VERSION.\"#1\".\"0000\".info.\"0409\".$field" "$WINRES_JSON" 2>/dev/null)" \
|
||||
"$CANONICAL" "winres.json $field"
|
||||
done
|
||||
|
||||
# Anchor on line start: the XML declaration on line 1 also carries a
|
||||
# version="1.0" attribute.
|
||||
check_expected "cmd/bd/winres/manifest.xml" \
|
||||
"$(grep -oE '^[[:space:]]*version="[0-9][^"]*"' cmd/bd/winres/manifest.xml 2>/dev/null | head -1 | sed -E 's/.*"(.*)"/\1/')" \
|
||||
"$BASE_VERSION.0" "manifest.xml assemblyIdentity version"
|
||||
|
||||
echo ""
|
||||
|
||||
if [ $MISMATCH -eq 1 ]; then
|
||||
echo -e "${RED}❌ Version mismatch detected!${NC}"
|
||||
echo ""
|
||||
echo "Run: scripts/update-versions.sh $CANONICAL"
|
||||
echo "Or manually update the mismatched files."
|
||||
echo "Note: re-running 'scripts/update-versions.sh $CANONICAL' will NOT fix"
|
||||
echo "most of these. It derives the OLD version from cmd/bd/version.go, which"
|
||||
echo "already reads $CANONICAL, so its old->new substitutions rewrite"
|
||||
echo "$CANONICAL -> $CANONICAL and no-op on a file that drifted. Only the"
|
||||
echo ".githooks markers (rewritten wholesale) and uv.lock (regenerated) heal"
|
||||
echo "on a re-run."
|
||||
echo ""
|
||||
echo "Fix whichever applies:"
|
||||
echo " • cmd/bd/version.go itself is wrong (you meant another version):"
|
||||
echo " scripts/update-versions.sh <intended-version>"
|
||||
echo " • one gated file drifted: edit that file to $CANONICAL and re-run"
|
||||
echo " this script."
|
||||
echo " • several drifted: set cmd/bd/version.go back to the previous"
|
||||
echo " version, then scripts/update-versions.sh $CANONICAL to replay the"
|
||||
echo " whole bump."
|
||||
exit 1
|
||||
else
|
||||
echo -e "${GREEN}✓ Version files and released-docs policy pass for: $CANONICAL${NC}"
|
||||
echo -e "${GREEN}✓ Version files in sync at: $CANONICAL${NC}"
|
||||
echo " (Version files only — this script does not check docs. The docs"
|
||||
echo " release line and docs/cli-docs.pin are manual release steps; see"
|
||||
echo " RELEASING.md.)"
|
||||
fi
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue