* Releasing

Read the content below for the release process.

** Before the first publish
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.

** Every release
1. Bump the version in =Cargo.toml=, and build once so =Cargo.lock= follows.
2. Test and package the release.

   #+begin_src sh
   cargo test
   cargo clippy --all-targets -- -D warnings
   cargo run -- build docs -o docs/_site --strict
   cargo package
   #+end_src

3. Build a site you know with =--no-cache= and diff the output against the previous
   version's.
4. Commit, tag, push.

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

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.

** If a release goes wrong
Yank rather than delete, and ship a fix as a new version:

#+begin_src sh
cargo yank --version 0.18.0
#+end_src

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