2.7 KiB
2.7 KiB
Release Stability Gate
A release MUST NOT ship until the stability gate passes. This gate protects users from silent upgrade regressions like mode flips, missing config, and data-path changes.
Upgrade Matrix
Every release candidate must pass upgrade smoke tests from these starting points:
| From Version | Mode | Scenario |
|---|---|---|
| Previous release (N-1) | Embedded (maintainer) | Init → create issues → upgrade → verify data + role |
| Previous release (N-1) | Shared-server (maintainer) | Init → create issues → upgrade → verify routing + data |
| Previous release (N-1) | Contributor | Init --contributor → upgrade → verify role preserved |
| Two releases back (N-2) | Embedded (maintainer) | Init → upgrade → verify schema migration |
What each scenario verifies
- Data preservation: issues created before upgrade are visible after upgrade
- Mode preservation:
embeddedstaysembedded,shared-serverstaysshared-server - Role preservation:
beads.rolegit config is not cleared or changed - Config continuity:
bd doctor quickpasses after upgrade - No silent errors: upgrade path produces no unexpected warnings or errors
Running the Gate
# Run all upgrade smoke tests
make test-upgrade
# Or directly:
./scripts/upgrade-smoke-test.sh
The script:
- Downloads the previous release binary (cached in
~/.cache/beads-regression/) - Creates isolated workspaces for each scenario
- Initialises with the old binary, creates test data
- Runs
bd initwith the candidate binary (simulating upgrade) - Verifies data, role, and mode are preserved
- Reports pass/fail for each scenario
Release Checklist Integration
Before cutting a release, the release process (see RELEASING.md) requires:
- Upgrade smoke tests pass (
make test-upgrade) - Breaking changes documented in CHANGELOG.md with migration steps
- If config/schema migration is involved: recovery steps documented
- Regression tests pass (
make test-regression)
Sign-off
The person cutting the release is responsible for verifying the gate passes. If any scenario fails, the release is blocked until the failure is resolved.
Gate failures block the release — there is no override. Fix the bug or document the breaking change with explicit migration steps before shipping.