SporeVM is intentionally staying pre-1.0 for now. Do not cut v1.0.0 or any
later major version unless the user explicitly says to release 1.0.0 now.
If svu next suggests v1.0.0 because of breaking changes, treat that as a
signal for the next 0.x.0 minor instead; use patch releases only for fixes.
-
Fetch and orient:
git fetch origin --tags --prune
git status --short --branch
gh release list --repo sporevm/sporevm --limit 10
git log --oneline <last-tag>..origin/main
Check live PR, GitHub status, and Buildkite state before making a release
call. Use svu next and commit scope to inform the version, but set the
final tag explicitly as vMAJOR.MINOR.PATCH.
Version policy:
- Fix-only changes: next
v0.x.PATCH.
- Features or breaking changes: next
v0.MINOR.0.
svu next returning v1.0.0 is not permission to cross 1.0.0; stop
or choose the next pre-1.0 minor unless the user explicitly overrides.
-
Prepare the version bump through a PR:
git switch -c lox/release-vX.Y.Z origin/main
MISE_TRUSTED_CONFIG_PATHS="$PWD/mise.toml" mise run release:prepare -- vX.Y.Z
MISE_TRUSTED_CONFIG_PATHS="$PWD/mise.toml" mise run check
./zig-out/bin/spore version
git-assume bk-codex
git add build.zig src/version.zig
git commit -m "chore: Bump version to vX.Y.Z"
git push -u origin lox/release-vX.Y.Z
PR title should be chore: Bump version to vX.Y.Z. Keep the PR body short:
why the release is needed and what user-visible changes it carries. Do not
add a validations section.
-
Merge only after the PR Buildkite status is green. If origin/main moves
before merge, rebase the bump branch onto origin/main, rerun
mise run check, and force-push with lease.
-
After merge, wait for the main Buildkite status on the merge commit to pass:
gh api repos/sporevm/sporevm/commits/$(git rev-parse origin/main)/status \
--jq '{state: .state, statuses: [.statuses[] | {context,state,description,target_url}]}'
bk build view -p buildkite/sporevm <main-build-number>
The benchmark trigger is async on main; do not block release tagging on the
child benchmark build unless the main status fails or the user asks.
-
Tag exactly once from detached origin/main:
git fetch origin --tags --prune
git tag -l vX.Y.Z
gh release view vX.Y.Z --repo sporevm/sporevm || true
git switch --detach origin/main
SPOREVM_RELEASE_VERSION=vX.Y.Z \
MISE_TRUSTED_CONFIG_PATHS="$PWD/mise.toml" \
mise run release
Stop if the tag or release already exists. Do not delete and recreate a
version tag to rerun publishing; watch or debug the existing tag build.
-
Watch the tag build and verify publishing:
tag_sha="$(git rev-list -n 1 vX.Y.Z)"
bk build list -p buildkite/sporevm --branch vX.Y.Z --commit "$tag_sha" --limit 10 --json
bk build view -p buildkite/sporevm <tag-build-number>
gh release view vX.Y.Z --repo sporevm/sporevm \
--json tagName,name,isDraft,isPrerelease,publishedAt,url,assets
Expected assets are checksums.txt, spore_Darwin_arm64.tar.gz,
spore_Linux_arm64.tar.gz, libspore_Darwin.tar.gz, and
libspore_Linux.tar.gz. The benchmark trigger can be skipped/broken on tag
builds; the release archive and publish jobs must pass.
-
Replace autogenerated GitHub release notes with human notes:
gh release view vX.Y.Z --repo sporevm/sporevm --json body,url
gh pr list --repo sporevm/sporevm --state merged --base main --limit 20 \
--json number,title,body,mergedAt,url
gh release edit vX.Y.Z --repo sporevm/sporevm --notes-file NOTES.md
Write notes in the recent Cleanroom/SporeVM style:
- Start with a short paragraph explaining what the release is for.
- Use
## Highlights with 2-4 user-facing subsections.
- Add
## Compatibility notes only when behavior, CLI, ABI, artifact names,
or release policy changed.
- Add validation details only when they are useful release evidence, not as
a noisy command transcript.
- End with
## Full changelog and the compare URL.
Do not leave the autogenerated ## What's Changed PR bullet list as the
final notes. Do not include version-bump PRs as release content. When GitHub
autogeneration includes deleted or mistaken release history, use the intended
compare range explicitly.
