* Releasing

Read the content below for the release process.

** Before the first publish
#+begin_src sh
cargo login          # a crates.io token, once per machine
cargo publish --dry-run
#+end_src

=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. Publish the crate.

   #+begin_src sh
   cargo publish
   #+end_src

   This is irreversible: a published version can be yanked but never replaced.

6. Finish the GitHub release. Pushing the tag builds binaries for macOS (arm64 and
   x86_64) and Linux (gnu and musl) and opens a /draft/ release with them attached.

** 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.