RELEASING.org

 1* Releasing
 2
 3Read the content below for the release process.
 4
 5** Where the repository lives
 6=origin= is gitbay (=ssh://git@gitbay.org/krz/orgo.git=), which is where the issues and
 7merge requests are. It push-mirrors to =https://github.com/krazywarez/orgo=, tags
 8included.
 9
10That mirror is what makes a release work. The automation is GitHub Actions and nothing
11triggers it directly: a tag pushed to gitbay reaches GitHub within a minute, and
12=.github/workflows/release.yml= runs there. =docs.yml= deploys the documentation site to
13Pages the same way, on a push to =main= that touches =docs/=, =src/=, =Cargo.toml= or
14=Cargo.lock=.
15
16Neither forge runs the tests. =ci.yml= is gone and there is no =.gitbay/ci.yml=, so the
17checks in step 2 are the only gate a release passes.
18
19** Before the first publish
20Nothing to install and no token to store. The release workflow mints a short-lived
21crates.io token with OIDC, configured on crates.io against the GitHub repository, the
22=release.yml= workflow file and the =crates-io= environment that job runs in.
23
24=repository= in =Cargo.toml= points at gitbay; =homepage= points at the documentation
25site on Pages.
26
27** Every release
281. Bump the version in =Cargo.toml=, and build once so =Cargo.lock= follows.
292. Test and package the release.
30
31   #+begin_src sh
32   cargo test
33   cargo clippy --all-targets -- -D warnings
34   cargo run -- build docs -o docs/_site --strict
35   cargo package
36   #+end_src
37
383. Build a site you know with =--no-cache= and diff the output against the previous
39   version's.
404. Commit, tag, push.
41
42   #+begin_src sh
43   git commit -am "0.18: <what changed>"
44   git tag -a v0.18.0 -m "0.18.0"
45   git push && git push --tags
46   #+end_src
47
485. The tag push is the release, by way of the mirror. It builds binaries for macOS
49   (arm64 and x86_64) and Linux (gnu and musl), opens a /draft/ GitHub release with them
50   attached, and runs =cargo publish --locked= — there is nothing to publish by hand, and
51   running =cargo publish= locally now only fails on a version crates.io already has. The
52   build checks the tag against =Cargo.toml= rather than trusting the two to match.
53
54   =gh= talks to the mirror, so it is how you watch the run:
55
56   #+begin_src sh
57   gh run list -R krazywarez/orgo --limit 3
58   #+end_src
59
60   Publishing is the one step that cannot be undone: a version can be yanked but never
61   replaced. The publish job runs in the =crates-io= environment so it can be held —
62   add a required reviewer to that environment in the GitHub repository settings and a
63   tag push waits for a human before it reaches crates.io.
64
65   A release that fails halfway is re-run from the Actions tab: the workflow takes the
66   tag to build as an input, so it does not need a second tag.
67
686. Write the release notes and publish the draft GitHub release.
697. Release on gitbay, which has no automation of its own. Same notes, same binaries.
70
71   #+begin_src sh
72   gitbay release create v0.18.0 --title 0.18.0 --file - < notes.md
73   gh release download v0.18.0 -R krazywarez/orgo -D dist
74   for f in dist/*; do gitbay release asset add v0.18.0 "$(basename "$f")" < "$f"; done
75   #+end_src
76
77** If a release goes wrong
78Yank rather than delete, and ship a fix as a new version:
79
80#+begin_src sh
81cargo yank --version 0.18.0
82#+end_src
83
84Yanking stops new dependents from selecting it; anyone who already has it keeps working.
85Then release =0.18.1= with the fix.