perga 0.1.5

A terminal Markdown browser with a persistent file tree, tabs, wiki-links and backlinks
Documentation
# 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"
./perga --print README.md | head
man -l perga.1 | head
```

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.