krz/orgo

 1* Releasing
 2
 3Read the content below for the release process.
 4
 5** Before the first publish
 6#+begin_src sh
 7cargo login          # a crates.io token, once per machine
 8cargo publish --dry-run
 9#+end_src
10
11=repository= and =homepage= in =Cargo.toml= point at GitHub and at the documentation site
12on Pages.
13
14** Every release
151. Bump the version in =Cargo.toml=, and build once so =Cargo.lock= follows.
162. Test and package the release.
17
18   #+begin_src sh
19   cargo test
20   cargo clippy --all-targets -- -D warnings
21   cargo run -- build docs -o docs/_site --strict
22   cargo package
23   #+end_src
24
253. Build a site you know with =--no-cache= and diff the output against the previous
26   version's.
274. Commit, tag, push.
28
29   #+begin_src sh
30   git commit -am "0.18: <what changed>"
31   git tag -a v0.18.0 -m "0.18.0"
32   git push && git push --tags
33   #+end_src
34
355. Publish the crate.
36
37   #+begin_src sh
38   cargo publish
39   #+end_src
40
41   This is irreversible: a published version can be yanked but never replaced.
42
436. Finish the GitHub release. Pushing the tag builds binaries for macOS (arm64 and
44   x86_64) and Linux (gnu and musl) and opens a /draft/ release with them attached.
45
46** If a release goes wrong
47Yank rather than delete, and ship a fix as a new version:
48
49#+begin_src sh
50cargo yank --version 0.18.0
51#+end_src
52
53Yanking stops new dependents from selecting it; anyone who already has it keeps working.
54Then release =0.18.1= with the fix.