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, merge
  7requests, builds and releases are. It push-mirrors to
  8=https://github.com/krazywarez/orgo=, tags included, but nothing in a release depends on
  9that mirror any more — it is a copy, not a step.
 10
 11** What runs where
 12Three things happen automatically, and one of them happens on your Mac.
 13
 14| Trigger            | Where                     | What                                              |
 15|--------------------+---------------------------+---------------------------------------------------|
 16| Any branch push    | gitbay CI (=test= job)    | =cargo test=, clippy, and a =--strict= docs build |
 17| A push to =main=   | gitbay CI (=pages= job)   | Publishes the site to the =pages= branch          |
 18| A =v*= tag push    | Your Mac (=pre-push=)     | Builds and packages the two darwin tarballs       |
 19| A =v*= tag push    | gitbay CI (=release= job) | Linux tarballs, the release, then crates.io       |
 20
 21The darwin binaries are the one part CI cannot do. The runner is Linux, and gitbay's
 22=runner next= claims the oldest pending build with no platform targeting, so a second
 23runner could not be aimed at macOS jobs. Building them in =pre-push= is the better place
 24anyway: a build failure aborts the push, so a tag whose Mac binaries do not compile is
 25never published.
 26
 27Uploading them has to wait, because =release asset add= needs a release and the release is
 28created by the job the tag push triggers. =pre-push= hands that to a detached
 29=.githooks/upload-macos=, which waits for the release and then attaches the tarballs. Its
 30log and the tarballs stay in =dist/macos/<tag>/=.
 31
 32** Before the first publish
 33Once per clone:
 34
 35#+begin_src sh
 36git config core.hooksPath .githooks
 37#+end_src
 38
 39Once on the Mac that cuts releases — Homebrew's =rust= cannot add targets, so the
 40toolchain has to be rustup:
 41
 42#+begin_src sh
 43brew install rustup && rustup default stable
 44rustup target add x86_64-apple-darwin
 45#+end_src
 46
 47Once on the VPS runner: a Rust toolchain with =x86_64-unknown-linux-musl= added and
 48=musl-gcc= installed, and an SSH key registered on gitbay that can push to the repository
 49(the =pages= job) and run =release create= (the =release= job).
 50
 51Once on the repository — the crates.io token, which is the one credential this setup
 52stores:
 53
 54#+begin_src sh
 55gitbay repo secret set krz/orgo CARGO_REGISTRY_TOKEN
 56#+end_src
 57
 58=repository= in =Cargo.toml= points at gitbay; =homepage= points at
 59[[https://orgo.krz.sh]], the documentation site the =pages= job publishes.
 60
 61** Every release
 621. Bump the version in =Cargo.toml=, and build once so =Cargo.lock= follows.
 632. Test and package the release. CI runs the first two on every push, but a release is
 64   worth checking before you tag rather than after.
 65
 66   #+begin_src sh
 67   cargo test
 68   cargo clippy --all-targets -- -D warnings
 69   cargo run -- build docs -o docs/_site --strict
 70   cargo package
 71   #+end_src
 72
 733. Build a site you know with =--no-cache= and diff the output against the previous
 74   version's.
 754. Commit and push. The =test= and =pages= jobs run.
 76
 77   #+begin_src sh
 78   git commit -am "0.24: <what changed>"
 79   git push
 80   #+end_src
 81
 825. Write the release notes, then tag with them. The =release= job uses the tag's own
 83   annotation as the release notes, so the notes are written at the moment you decide to
 84   cut the release rather than afterwards.
 85
 86   #+begin_src sh
 87   $EDITOR notes.md
 88   git tag -a v0.24.0 -F notes.md
 89   git push --tags
 90   #+end_src
 91
 92   The push blocks while your Mac builds both darwin targets. If either fails, the push
 93   is refused and nothing is tagged.
 94
 956. The tag push is the release. It checks the tag against =Cargo.toml= rather than
 96   trusting the two to match, builds the gnu and musl tarballs, creates the release with
 97   your notes, attaches the tarballs, and runs =cargo publish --locked=. The macOS
 98   tarballs arrive a few minutes later from the detached uploader.
 99
100   #+begin_src sh
101   gitbay build list krz/orgo
102   gitbay release show krz/orgo v0.24.0
103   #+end_src
104
105   Publishing is the one step that cannot be undone: a version can be yanked but never
106   replaced. It runs last, after the release exists and the binaries are attached, so a
107   failure earlier in the job costs you a tag rather than a version number.
108
1097. If the macOS upload did not land — check =dist/macos/v0.24.0/upload.log= — rerun it.
110   The tarballs are already built, and uploading one twice replaces it.
111
112   #+begin_src sh
113   .githooks/upload-macos v0.24.0
114   #+end_src
115
116** If a release goes wrong
117Yank rather than delete, and ship a fix as a new version:
118
119#+begin_src sh
120cargo yank --version 0.24.0
121#+end_src
122
123Yanking stops new dependents from selecting it; anyone who already has it keeps working.
124Then release =0.24.1= with the fix.
125
126A build that failed halfway is re-run with =gitbay build trigger=, which does not need a
127second tag.