# Publishing
How a release of perga is cut, and what each artefact is for.
## The pipeline
`.github/workflows/release.yml` is generated by
[`dist`](https://opensource.axo.dev/cargo-dist/) from `dist-workspace.toml` and
committed unmodified. **Do not edit it by hand** — change the configuration and
run `dist generate`, which CI also checks.
The configuration asks for the two musl targets, a shell installer, sha256
checksums, GitHub attestations, and GitHub Releases as the host. `aarch64` is
cross-compiled; `dist` reaches for `cargo-zigbuild` itself when it sees a cross
build, so nothing extra is configured for it.
## Release checklist
1. **Bump the version** in `Cargo.toml`, and run `cargo check` so `Cargo.lock`
follows.
2. **Update `CHANGELOG.md`**: move `Unreleased` into a dated version heading and
start a fresh `Unreleased`.
3. **Regenerate the demo GIF**: `cd demo && vhs demo.tape`. Commit the result.
4. **Check the tree is clean**: `cargo fmt --all -- --check`,
`cargo clippy --all-targets --all-features -- -D warnings`, `cargo test`,
`cargo deny check`, `cargo publish --dry-run`.
5. **Tag it**: `git tag -a v0.1.0 -m "perga 0.1.0" && git push origin v0.1.0`.
6. **Wait for the release workflow.** Pushing a `v*` tag runs
`.github/workflows/release.yml`, which builds both musl targets, generates
the man page and the completions from the freshly built binary, and attaches
the tarballs, the checksums, and the installer to a GitHub Release.
7. **Update `packaging/PKGBUILD`**: the `pkgver`, and the `sha256sums` for each
architecture from the release's `.sha256` files. See
[`packaging/README.md`](../packaging/README.md).
8. **Publish the crate**: `cargo publish`.
Steps 5 to 8 are in that order for a reason: the AUR checksums come from the
release artefacts, and crates.io cannot be un-published.
## What ships in a release
Each `perga-<target>.tar.xz` contains one directory named after the target,
holding:
```
perga the binary
perga.1 the man page
completions/perga.bash
completions/perga.zsh
completions/perga.fish
LICENSE-MIT
LICENSE-APACHE
README.md
CHANGELOG.md
```
Alongside the archives, the release carries a `.sha256` for each of them, a
`sha256.sum` covering all of them, the four generated files on their own, the
source tarball, and `perga-installer.sh`.
The man page and the completions are generated by `packaging/generate-assets.sh`,
which runs the binary that is about to ship — `perga --generate-man`,
`perga --generate-completions bash` — rather than by a `build.rs`. Sharing the `clap` definition with a build script
means duplicating or `#[path]`-including the CLI module, which is fragile for
no benefit, and generating them from the shipped binary means they cannot
describe a different version from the one in the tarball.
## Targets
- `x86_64-unknown-linux-musl`
- `aarch64-unknown-linux-musl`
musl, so that a binary built on a current distribution runs on an old one.
`GLIBC_2.xx not found` is the most common bug report a Rust CLI receives and
it is entirely avoidable.
`aarch64` is cross-compiled with `cargo-zigbuild`.
`syntect` must be built with `default-fancy` and without default features; the
default `onig` backend links a C library and fails a musl build. This is
already set in `Cargo.toml` — do not "simplify" it.
## Versioning
SemVer. Before 1.0, a breaking change to the configuration format or to a
default keybinding is a minor bump and gets a `Changed` entry in the changelog
saying exactly what to edit.
The session file and the index cache both carry a format version and are
discarded on a mismatch, so neither needs a migration.
## Verifying a release by hand
```sh
# In a container with an old glibc, to prove the musl build is really static:
tar xJf perga-x86_64-unknown-linux-musl.tar.xz
cd perga-x86_64-unknown-linux-musl
./perga --version
ldd ./perga # "not a dynamic executable"
```
The release workflow does the first two; the container check is worth doing by
hand on a first release and after any dependency change that pulls in C code.