ContextQMD
Back to Beads

v1.2.2 release test plan

docs/releases/v1.2.2-test-plan.md

1.2.23.8 KB
Original Source

v1.2.2 release test plan

v1.2.2 is the recovery re-release after the accidental v1.2.0/v1.2.1 publish: the v1.1.2 tree under a higher version, plus four deliberate deltas. This plan covers exactly those deltas plus the recovery paths; the underlying code is otherwise the already-tested v1.1.2 release.

What changed vs v1.1.2 (review surface)

  1. Version bump to 1.2.2 via scripts/update-versions.sh (version.go, plugins, marketplace, MCP, npm, nix, winres, docs snapshot version-1.2.2, uv.lock re-pin).
  2. go.mod retract block for v1.2.1 / v1.2.0 / v1.1.1.
  3. Incident-aware forward-skew message in internal/storage/schema/schema.go (+ two new pinned tests), and docs/RECOVERY-1.2.1.md.
  4. CHANGELOG [1.2.2] entry and cmd/bd/info.go versionChanges entry.
  5. This test plan and scripts/release-verification-1.2.2.sh.

No workflow or release-script files changed: the tag runs the exact pipeline that shipped v1.1.2.

Automated verification (run before tagging)

sh
# build a v1.2.1 binary once (needed for the migrated-DB legs):
git worktree add /tmp/src-121 v1.2.1
(cd /tmp/src-121 && CGO_ENABLED=1 go build -tags gms_pure_go -o /tmp/bd-1.2.1 ./cmd/bd)

BD_121=/tmp/bd-1.2.1 ./scripts/release-verification-1.2.2.sh

The script must end 0 failed. It proves: candidate identity and unit tests (L1), fresh-workspace round-trip at schema v53 (L2), clean reopen (L3), the incident refusal message on a v1.2.1-migrated v65 database with no "install the latest release" loop (L4), byte-identical reads and working writes under BD_IGNORE_SCHEMA_SKEW=1 (L5), the runbook's cursor rollback restoring guard-free operation (L6), the runbook's optional events re-track (L7), idempotent re-migration by a 1.2.1 binary after recovery — the "future tested 1.2.x upgrade still works" guarantee (L8), and the strict tag-mode version-consistency gate (L9).

Full-suite gate

The v1.1.2 tree's own test suite must stay green with only the intended skew-message diff:

sh
go build ./... && go vet ./...
go test ./internal/storage/schema/ -count=1
go test ./cmd/bd/ -run 'TestSchema|TestVersion|TestInfo' -count=1

(A full go test ./... matches what v1.1.2 shipped with; the packages above are the only ones whose sources changed.)

Manual checklist (human, before/at tagging)

  • Review the diff git diff v1.1.2..release/v1.2.2 — nothing outside the five deltas listed above.
  • git log v1.1.2..release/v1.2.2 — commits are only this release's.
  • Read docs/RECOVERY-1.2.1.md as an affected user; commands are copy-pasteable.
  • Tag v1.2.2 on the release branch head; the tag-triggered release.yml must go green end to end (version gates, MCP/npm/ website package gates, goreleaser linux+macos, attestation, PyPI, npm).
  • Do NOT touch the existing v1.2.1 tag or its GitHub release assets (Homebrew's formula pins that tarball's checksum).

Manual checklist (after the release exists)

  • GitHub: v1.2.2 marked Latest (v1.2.1 stays pre-release); curl -s https://api.github.com/repos/gastownhall/beads/releases/latest returns v1.2.2 → install.sh / install.ps1 / doctor nag follow.
  • Homebrew: brew bump-formula-pr with the v1.2.2 tarball; after merge, brew upgrade beads on a 1.2.1 machine lands 1.2.2 and brew test beads passes.
  • npm: npm dist-tag ls @beads/bd shows latest: 1.2.2; npm deprecate @beads/[email protected] "accidental untested release — see docs/RECOVERY-1.2.1.md".
  • PyPI: yank beads-mcp==1.2.1 (and 1.2.0 if present).
  • Go proxy: go install github.com/steveyegge/beads/cmd/bd@latest resolves v1.2.2 (retracts may take a proxy-cache cycle to appear).
  • Smoke on a real Homebrew machine that ran 1.2.1: upgrade → incident message appears → runbook cursor rollback → clean operation.