diff --git a/.beads/formulas/beads-release.formula.toml b/.beads/formulas/beads-release.formula.toml index fb710725d..3c2711f54 100644 --- a/.beads/formulas/beads-release.formula.toml +++ b/.beads/formulas/beads-release.formula.toml @@ -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` 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. diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 99fe2466f..aad41ecfb 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -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" } ] } diff --git a/.githooks/post-checkout b/.githooks/post-checkout index b2fdb3c35..19d309b87 100755 --- a/.githooks/post-checkout +++ b/.githooks/post-checkout @@ -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 --- diff --git a/.githooks/post-merge b/.githooks/post-merge index a6250a7da..4d315045b 100755 --- a/.githooks/post-merge +++ b/.githooks/post-merge @@ -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 --- diff --git a/.githooks/pre-commit b/.githooks/pre-commit index b77f8d207..46e710a33 100755 --- a/.githooks/pre-commit +++ b/.githooks/pre-commit @@ -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 --- diff --git a/.githooks/pre-push b/.githooks/pre-push index 3d01c6ecf..8bcc2483b 100755 --- a/.githooks/pre-push +++ b/.githooks/pre-push @@ -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 --- diff --git a/.githooks/prepare-commit-msg b/.githooks/prepare-commit-msg index 8cd65fddc..bf8cfb8ff 100755 --- a/.githooks/prepare-commit-msg +++ b/.githooks/prepare-commit-msg @@ -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 --- diff --git a/.github/workflows/conformance.yml b/.github/workflows/conformance.yml index 6c33bcd77..e981539db 100644 --- a/.github/workflows/conformance.yml +++ b/.github/workflows/conformance.yml @@ -5,7 +5,7 @@ name: Conformance on: pull_request: - branches: [ main ] + branches: [ main, 'release/**' ] merge_group: concurrency: diff --git a/.github/workflows/cross-version-smoke.yml b/.github/workflows/cross-version-smoke.yml index 425c07bde..d9f5c7a71 100644 --- a/.github/workflows/cross-version-smoke.yml +++ b/.github/workflows/cross-version-smoke.yml @@ -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: diff --git a/.github/workflows/pr-risk.yml b/.github/workflows/pr-risk.yml index f640f65b2..60ba8ca75 100644 --- a/.github/workflows/pr-risk.yml +++ b/.github/workflows/pr-risk.yml @@ -2,7 +2,7 @@ name: PR Risk on: pull_request: - branches: [ main ] + branches: [ main, 'release/**' ] merge_group: concurrency: diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml index 0e1aab6ab..3b19296bc 100644 --- a/.github/workflows/pr.yml +++ b/.github/workflows/pr.yml @@ -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: diff --git a/.github/workflows/regression.yml b/.github/workflows/regression.yml index e2dc2e910..46237752b 100644 --- a/.github/workflows/regression.yml +++ b/.github/workflows/regression.yml @@ -5,7 +5,7 @@ on: push: branches: [main] pull_request: - branches: [main] + branches: [main, 'release/**'] # Allow manual trigger workflow_dispatch: diff --git a/CHANGELOG.md b/CHANGELOG.md index 5748fe559..aa5354a07 100644 --- a/CHANGELOG.md +++ b/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 # 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 ` 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 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 `/.beads` is `/.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 )` 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 --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 --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 `.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 + `operatorRFC3339 timestampreason` 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. + + +- 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. + + + +### 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 diff --git a/RELEASING.md b/RELEASING.md index 8dab676a0..894abbb20 100644 --- a/RELEASING.md +++ b/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 +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 ` 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` 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 && 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 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 --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 ` 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, diff --git a/cmd/bd/info.go b/cmd/bd/info.go index 06e5c5386..fe3c62f99 100644 --- a/cmd/bd/info.go +++ b/cmd/bd/info.go @@ -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 ' 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 ' 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 --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 --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", diff --git a/cmd/bd/version.go b/cmd/bd/version.go index b1542ea6e..3bf32c13f 100644 --- a/cmd/bd/version.go +++ b/cmd/bd/version.go @@ -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) diff --git a/cmd/bd/winres/manifest.xml b/cmd/bd/winres/manifest.xml index e9fb28697..5623c89ce 100644 --- a/cmd/bd/winres/manifest.xml +++ b/cmd/bd/winres/manifest.xml @@ -3,7 +3,7 @@ beads - AI-supervised issue tracker diff --git a/cmd/bd/winres/winres.json b/cmd/bd/winres/winres.json index e2c515a26..b3c9a8137 100644 --- a/cmd/bd/winres/winres.json +++ b/cmd/bd/winres/winres.json @@ -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" } } } diff --git a/default.nix b/default.nix index af8d26fac..6bbc63ec4 100644 --- a/default.nix +++ b/default.nix @@ -7,7 +7,7 @@ }: buildGoModule { pname = "beads"; - version = "1.2.2"; + version = "1.3.0"; src = self; diff --git a/docs/getting-started/upgrading.md b/docs/getting-started/upgrading.md index d6d060b4e..0a58320c2 100644 --- a/docs/getting-started/upgrading.md +++ b/docs/getting-started/upgrading.md @@ -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 # 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 diff --git a/docs/index.md b/docs/index.md index 562585852..bc3073d76 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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? diff --git a/docs/recovery/index.md b/docs/recovery/index.md index f7eb170f7..647d6ff0d 100644 --- a/docs/recovery/index.md +++ b/docs/recovery/index.md @@ -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) | diff --git a/integrations/beads-mcp/pyproject.toml b/integrations/beads-mcp/pyproject.toml index a449c8caa..412c678c5 100644 --- a/integrations/beads-mcp/pyproject.toml +++ b/integrations/beads-mcp/pyproject.toml @@ -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" diff --git a/integrations/beads-mcp/src/beads_mcp/__init__.py b/integrations/beads-mcp/src/beads_mcp/__init__.py index 4a1373fef..2c222f1f7 100644 --- a/integrations/beads-mcp/src/beads_mcp/__init__.py +++ b/integrations/beads-mcp/src/beads_mcp/__init__.py @@ -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" diff --git a/integrations/beads-mcp/uv.lock b/integrations/beads-mcp/uv.lock index 9cfb3ae5d..2dde92ec1 100644 --- a/integrations/beads-mcp/uv.lock +++ b/integrations/beads-mcp/uv.lock @@ -175,7 +175,7 @@ wheels = [ [[package]] name = "beads-mcp" -version = "1.2.2" +version = "1.3.0" source = { editable = "." } dependencies = [ { name = "fastmcp" }, diff --git a/npm-package/package.json b/npm-package/package.json index b32f897bd..eedd8c5da 100644 --- a/npm-package/package.json +++ b/npm-package/package.json @@ -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": { diff --git a/plugins/beads/.claude-plugin/plugin.json b/plugins/beads/.claude-plugin/plugin.json index 78a7e8052..f861043e2 100644 --- a/plugins/beads/.claude-plugin/plugin.json +++ b/plugins/beads/.claude-plugin/plugin.json @@ -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" diff --git a/plugins/beads/.codex-plugin/plugin.json b/plugins/beads/.codex-plugin/plugin.json index e059be0a8..bf76223b3 100644 --- a/plugins/beads/.codex-plugin/plugin.json +++ b/plugins/beads/.codex-plugin/plugin.json @@ -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", diff --git a/plugins/beads/.copilot-plugin/plugin.json b/plugins/beads/.copilot-plugin/plugin.json index 2a217ac6b..90a496a43 100644 --- a/plugins/beads/.copilot-plugin/plugin.json +++ b/plugins/beads/.copilot-plugin/plugin.json @@ -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" diff --git a/scripts/check-versions.sh b/scripts/check-versions.sh index e8550f3db..90b515d7e 100755 --- a/scripts/check-versions.sh +++ b/scripts/check-versions.sh @@ -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 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 " + 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