krz/orgo

 1# Releasing
 2
 3A release is three things that must agree: a version in `Cargo.toml`, a git tag, and a
 4changelog entry. The release workflow checks the first two against each other and refuses
 5to build if they differ, because a release tagged `v0.18.0` containing a binary that
 6reports `0.17.0` is the kind of mistake nobody notices for months.
 7
 8## Before the first publish
 9
10```bash
11cargo login          # a crates.io token, once per machine
12cargo publish --dry-run
13```
14
15`repository` and `homepage` in `Cargo.toml` point at GitHub and at the documentation site
16on Pages. If git.krz.sh becomes the primary remote, `repository` should follow it —
17crates.io shows that link on the crate page, and it should lead somewhere you read.
18
19## Every release
20
211. **Write the changelog entry first.** [CHANGELOG.md](CHANGELOG.md) names behaviour, not
22   commits — someone reading it wants to know what their next build will do differently.
23   Anything that changes rendered HTML gets said out loud.
24
252. **Bump the version** in `Cargo.toml`, and build once so `Cargo.lock` follows.
26
27   Patch for fixes that change nothing about the stable surface. Minor for new config
28   keys, new template variables, an MSRV bump, or output that changes to track Emacs more
29   closely. Major for anything that breaks the promises in the README's Compatibility
30   section — config keys, template context, CLI, or URLs.
31
323. **Check it.**
33
34   ```bash
35   cargo test
36   cargo clippy --all-targets -- -D warnings
37   cargo run -- build docs -o docs/_site --strict
38   cargo package
39   ```
40
41   `cargo package` is the one people forget: it builds the crate exactly as crates.io will
42   receive it, and catches a file the `exclude` list should not have removed.
43
444. **Verify against a real corpus.** The test suite says the code does what it did; a
45   corpus says the *site* does. Build a site you know with `--no-cache` and diff the
46   output against the previous version's. A release that quietly changes 200 pages should
47   do so on purpose.
48
495. **Commit, tag, push.**
50
51   ```bash
52   git commit -am "0.18: <what changed>"
53   git tag -a v0.18.0 -m "0.18.0"
54   git push && git push --tags
55   ```
56
576. **Publish the crate.**
58
59   ```bash
60   cargo publish
61   ```
62
63   This is irreversible: a published version can be yanked but never replaced.
64
657. **Finish the GitHub release.** Pushing the tag builds binaries for macOS (arm64 and
66   x86_64) and Linux (gnu and musl) and opens a *draft* release with them attached. Paste
67   the changelog entry in and publish it. The draft is deliberate — a release that
68   publishes itself before anyone has read it cannot be edited quietly.
69
70## If a release goes wrong
71
72Yank rather than delete, and ship a fix as a new version:
73
74```bash
75cargo yank --version 0.18.0
76```
77
78Yanking stops new dependents from selecting it; anyone who already has it keeps working.
79Then release `0.18.1` with the fix and a changelog entry that says what happened.