RELEASING.org

Nothing to install and no token to store. The release workflow mints a short-lived crates.io token with OIDC, configured on crates.io against this repository, the release.yml workflow file and the crates-io environment that job runs in.

repository and homepage in Cargo.toml point at GitHub and at the documentation site on Pages.

1. Bump the version in Cargo.toml, and build once so Cargo.lock follows.

2. Test and package the release.

   cargo test
   cargo clippy --all-targets -- -D warnings
   cargo run -- build docs -o docs/_site --strict
   cargo package

3. Build a site you know with --no-cache and diff the output against the previous version's.

4. Commit, tag, push.

   git commit -am "0.18: <what changed>"
   git tag -a v0.18.0 -m "0.18.0"
   git push && git push --tags

5. The tag push is the release. It builds binaries for macOS (arm64 and x86_64) and Linux (gnu and musl), opens a draft GitHub release with them attached, and runs cargo publish --locked — there is nothing to publish by hand, and running cargo publish locally now only fails on a version crates.io already has. Publishing is the one step that cannot be undone: a version can be yanked but never replaced. The publish job runs in the crates-io environment so it can be held — add a required reviewer to that environment in the repository settings and a tag push waits for a human before it reaches crates.io. A release that fails halfway is re-run from the Actions tab: the workflow takes the tag to build as an input, so it does not need a second tag.
6. Write the release notes and publish the draft.

Yank rather than delete, and ship a fix as a new version:

cargo yank --version 0.18.0

Yanking stops new dependents from selecting it; anyone who already has it keeps working. Then release 0.18.1 with the fix.