RELEASING.org

origin is gitbay (ssh://git@gitbay.org/krz/orgo.git), which is where the issues, merge requests, builds and releases are. It push-mirrors to https://github.com/krazywarez/orgo, tags included, but nothing in a release depends on that mirror any more — it is a copy, not a step.

Three things happen automatically, and one of them happens on your Mac.

The darwin binaries are the one part CI cannot do. The runner is Linux, and gitbay's runner next claims the oldest pending build with no platform targeting, so a second runner could not be aimed at macOS jobs. Building them in pre-push is the better place anyway: a build failure aborts the push, so a tag whose Mac binaries do not compile is never published.

Uploading them has to wait, because release asset add needs a release and the release is created by the job the tag push triggers. pre-push hands that to a detached .githooks/upload-macos, which waits for the release and then attaches the tarballs. Its log and the tarballs stay in dist/macos/<tag>/.

Once per clone:

git config core.hooksPath .githooks

Once on the Mac that cuts releases — Homebrew's rust cannot add targets, so the toolchain has to be rustup:

brew install rustup && rustup default stable
rustup target add x86_64-apple-darwin

Once on the VPS runner: a Rust toolchain with x86_64-unknown-linux-musl added and musl-gcc installed, and an SSH key registered on gitbay that can push to the repository (the pages job) and run release create (the release job).

Once on the repository — the crates.io token, which is the one credential this setup stores:

gitbay repo secret set krz/orgo CARGO_REGISTRY_TOKEN

repository in Cargo.toml points at gitbay; homepage points at https://orgo.krz.sh, the documentation site the pages job publishes.

1. Bump the version in Cargo.toml, and build once so Cargo.lock follows.

2. Test and package the release. CI runs the first two on every push, but a release is worth checking before you tag rather than after.

   cargo test
   cargo clippy --all-targets -- -D warnings
   cargo run -- build docs -o docs/_site --strict
   cargo package

3. Build a site you know with --no-cache and diff the output against the previous version's.

4. Commit and push. The test and pages jobs run.

   git commit -am "0.24: <what changed>"
   git push

5. Write the release notes, then tag with them. The release job uses the tag's own annotation as the release notes, so the notes are written at the moment you decide to cut the release rather than afterwards.

   $EDITOR notes.md
   git tag -a v0.24.0 -F notes.md
   git push --tags

   The push blocks while your Mac builds both darwin targets. If either fails, the push is refused and nothing is tagged.

6. The tag push is the release. It checks the tag against Cargo.toml rather than trusting the two to match, builds the gnu and musl tarballs, creates the release with your notes, attaches the tarballs, and runs cargo publish --locked. The macOS tarballs arrive a few minutes later from the detached uploader.

   gitbay build list krz/orgo
   gitbay release show krz/orgo v0.24.0

   Publishing is the one step that cannot be undone: a version can be yanked but never replaced. It runs last, after the release exists and the binaries are attached, so a failure earlier in the job costs you a tag rather than a version number.

7. If the macOS upload did not land — check dist/macos/v0.24.0/upload.log — rerun it. The tarballs are already built, and uploading one twice replaces it.

   .githooks/upload-macos v0.24.0

Yank rather than delete, and ship a fix as a new version:

cargo yank --version 0.24.0

Yanking stops new dependents from selecting it; anyone who already has it keeps working. Then release 0.24.1 with the fix.

A build that failed halfway is re-run with gitbay build trigger, which does not need a second tag.