* Releasing

Read the content below for the release process.

** Where the repository lives
=origin= is gitbay (=ssh://git@gitbay.org/krz/orgo.git=), which is where the issues and
merge requests are. It push-mirrors to =https://github.com/krazywarez/orgo=, tags
included.

That mirror is what makes a release work. The automation is GitHub Actions and nothing
triggers it directly: a tag pushed to gitbay reaches GitHub within a minute, and
=.github/workflows/release.yml= runs there. =docs.yml= deploys the documentation site to
Pages the same way, on a push to =main= that touches =docs/=, =src/=, =Cargo.toml= or
=Cargo.lock=.

Neither forge runs the tests. =ci.yml= is gone and there is no =.gitbay/ci.yml=, so the
checks in step 2 are the only gate a release passes.

** 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 the GitHub repository, the
=release.yml= workflow file and the =crates-io= environment that job runs in.

=repository= in =Cargo.toml= points at gitbay; =homepage= points 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, by way of the mirror. 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. The
   build checks the tag against =Cargo.toml= rather than trusting the two to match.

   =gh= talks to the mirror, so it is how you watch the run:

   #+begin_src sh
   gh run list -R krazywarez/orgo --limit 3
   #+end_src

   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 GitHub 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 GitHub release.
7. Release on gitbay, which has no automation of its own. Same notes, same binaries.

   #+begin_src sh
   gitbay release create v0.18.0 --title 0.18.0 --file - < notes.md
   gh release download v0.18.0 -R krazywarez/orgo -D dist
   for f in dist/*; do gitbay release asset add v0.18.0 "$(basename "$f")" < "$f"; done
   #+end_src

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