Cutting a release#

For maintainers. Installing and verifying a release is in install.md.

Steps#

1. Set version in Cargo.toml (for an alpha, 0.1.0-alpha.2 and so on), run cargo check to update Cargo.lock, and merge that through a reviewed pull request. Every Cargo.toml change makes release/release-config stale, so each release needs a fresh review of it.
2. On the merged commit, run scripts/gate.sh. snob check must pass: every obligation is either reviewed or exempt under the [ratchet] baseline.
3. Tag that commit v plus the version (v0.1.0-alpha.2, v1.2.3) and push the tag.
4. The release workflow builds a draft release; a version with a prerelease part (-alpha.1) is marked as a GitHub prerelease. Check it has four archives and SHA256SUMS, and that gh attestation verify passes for each archive. Then publish.

What the workflow enforces#

.github/workflows/release.yml runs on vX.Y.Z and vX.Y.Z-* tags.

• The tag equals v plus the Cargo.toml version, and Cargo.lock agrees (scripts/release-check.sh).
• The tagged commit is on the default branch, so the configuration and ratchet baseline in effect are ones that branch accepted.
• scripts/gate.sh all passes on the tagged commit, with full git history for the ratchet baseline. That includes snob check on this repository: inherited debt from before the baseline is exempt, but any review outstanding on a later change blocks the release.
• --locked and the pinned toolchain are used throughout.
• Permissions are denied by default. Build jobs can read and attest; only the last job can write, and only to create the draft.
• Every job uses a runner from the approved list in tests/dogfood.rs.

Targets and runners#

All jobs run on Blacksmith runners. Linux binaries are built on Ubuntu 22.04 so they run on glibc 2.35 and newer. Blacksmith has no Intel Macs, so the x86_64 macOS binary is never run on Intel hardware before release. On the first release run, check that the arm64 and macOS runners start and that Rosetta 2 installs.

Attestations need a public repository or GitHub Enterprise Cloud; without them only the checksums are available. There are no Windows binaries: snob may build there, but process cleanup is Unix-only and Windows has not been tested.