krz/orgo

 1* Releasing
 2
 3Read the content below for the release process.
 4
 5** Before the first publish
 6Nothing to install and no token to store. The release workflow mints a short-lived
 7crates.io token with OIDC, configured on crates.io against this repository, the
 8=release.yml= workflow file and the =crates-io= environment that job runs in.
 9
10=repository= and =homepage= in =Cargo.toml= point at GitHub and at the documentation site
11on Pages.
12
13** Every release
141. Bump the version in =Cargo.toml=, and build once so =Cargo.lock= follows.
152. Test and package the release.
16
17   #+begin_src sh
18   cargo test
19   cargo clippy --all-targets -- -D warnings
20   cargo run -- build docs -o docs/_site --strict
21   cargo package
22   #+end_src
23
243. Build a site you know with =--no-cache= and diff the output against the previous
25   version's.
264. Commit, tag, push.
27
28   #+begin_src sh
29   git commit -am "0.18: <what changed>"
30   git tag -a v0.18.0 -m "0.18.0"
31   git push && git push --tags
32   #+end_src
33
345. The tag push is the release. It builds binaries for macOS (arm64 and x86_64) and
35   Linux (gnu and musl), opens a /draft/ GitHub release with them attached, and runs
36   =cargo publish --locked= — there is nothing to publish by hand, and running
37   =cargo publish= locally now only fails on a version crates.io already has.
38
39   Publishing is the one step that cannot be undone: a version can be yanked but never
40   replaced. The publish job runs in the =crates-io= environment so it can be held —
41   add a required reviewer to that environment in the repository settings and a tag
42   push waits for a human before it reaches crates.io.
43
44   A release that fails halfway is re-run from the Actions tab: the workflow takes the
45   tag to build as an input, so it does not need a second tag.
46
476. Write the release notes and publish the draft.
48
49** If a release goes wrong
50Yank rather than delete, and ship a fix as a new version:
51
52#+begin_src sh
53cargo yank --version 0.18.0
54#+end_src
55
56Yanking stops new dependents from selecting it; anyone who already has it keeps working.
57Then release =0.18.1= with the fix.