fader_master/docs/releasing.md

183 lines
10 KiB
Markdown

# Preparing and publishing releases
Publication is a separate, deliberate maintainer operation. Preparing this
integration does not create tags, push commits, or publish assets.
## Release contract
- Package: `fader_master`, with binaries `fader_master`,
`fader_master_client`, and `fader_master_server` (all included together).
- Version: inherited from `[workspace.package].version` in the root manifest;
currently `0.1.0-rc.1`, expected tag `v0.1.0-rc.1`. Keep [CHANGELOG](../CHANGELOG.md)
aligned when changing the version. No independent script version constant.
- Target: `x86_64-unknown-linux-gnu`, release profile, locked dependencies.
This initial target deliberately excludes Windows and musl: the application
uses Linux ALSA, libudev, libpulse and Unix sockets. ARM is not yet qualified.
- Artifacts: both `.tgz` archives and standalone binaries, plus `SHA256SUMS`.
Archive: `fader_master-x86_64-unknown-linux-gnu-v0.1.0-rc.1.tgz`, containing
a directory of the same stem with all three executables. Raw names are
`<binary>-x86_64-unknown-linux-gnu-v0.1.0-rc.1`.
- Public Gitea repository: [MadGobblins/fader_master](https://proxy.dandaedre.com/gitea/MadGobblins/fader_master).
Release URL: `https://proxy.dandaedre.com/gitea/MadGobblins/fader_master/releases/tag/v0.1.0-rc.1`.
Development origin: `git@git.dandaedre.com:MadGobblins/fader_master.git`.
The exact mapping in [rust-release.toml](../rust-release.toml) directs the
publisher to HTTPS without rewriting Git's origin.
- Cargo-binstall metadata is present for public archive verification. Crates
remain `publish = false`; this workflow does not publish to crates.io. Use
`cargo binstall --git https://proxy.dandaedre.com/gitea/MadGobblins/fader_master fader_master`
only after a release actually exists, not a registry-only install command.
## Prerequisites
Install the [Linux build prerequisites](build.md), the pinned Rust toolchain,
Git, jq, Cross, a working Docker or Podman backend, and cargo-binstall.
Python 3 is needed only for the wrapper tests. ShellCheck is recommended.
Install the intentionally spelled `rust_realease` separately, with maintainer
approval; the wrapper never installs or upgrades tools:
```sh
cargo binstall --git https://proxy.dandaedre.com/gitea/idle-org/rust_realease rust_realease
rust_realease --version
rust_realease --help
```
Use a publisher built from upstream commit `ed2ce6e` or a later release
containing its Cross `pre-build` fix. The prebuilt `0.1.6-rc.2` executable
tested here still rejected that option; its version string alone is not
sufficient. The RC was published using a temporary build of that exact fix.
Rerun all dry-run/packaging checks before publishing. See the
[publisher guide](https://proxy.dandaedre.com/gitea/idle-org/rust_realease/src/branch/main/docs/advanced-usage.md).
[Cross.toml](../Cross.toml) uses the `0.2.5` x86-64 GNU image and installs ALSA,
Pulse and udev development packages inside the build container. That image's
ALSA library is too old for this application: use the digest-pinned override
under [Published RC build](#published-rc-build). The pinned
Rust toolchain and Cargo.lock constrain Rust builds. The container tag and apt
repositories are not digest/snapshot pinned, so bit-for-bit reproducibility
and the minimum supported runtime glibc version are not yet established.
Artifacts are dynamically linked: recipient systems need ALSA, libpulse and
libudev runtime libraries and a running Pulse-compatible audio service.
## Credentials and invocation
Store a token outside the checkout in a readable, regular file with restrictive
permissions (for example mode 600). Grant repository read and release write
permissions. Pass the file path, never the token value. Do not commit the file
or its path; do not run the wrapper under shell tracing (`sh -x`).
```sh
./release.sh /path/outside/checkout/token --dry-run
./release.sh /path/outside/checkout/token --compile-only
# Separately authorized publication, only after the checks below:
./release.sh /path/outside/checkout/token
```
The first line becomes `GITEA_TOKEN` only for the publisher; empty first lines
are rejected. Remaining lines are ignored. All extra arguments are forwarded
exactly, so review them: preparation/push/replacement options are powerful and
are never added automatically. Invocation from another directory works.
Cargo metadata resolves the selected member's workspace-inherited version;
a hyphenated version automatically adds `--prerelease`. Stable versions do not.
The wrapper neither changes Git nor repairs metadata on its own.
For a token-free preview or local packaging, invoke the publisher directly:
```sh
rust_realease . --package fader_master --artifact-format both --dry-run
rust_realease . --package fader_master --artifact-format both --compile-only
```
## Verification and publication checklist
1. Preserve and resolve outstanding work intentionally; publication requires a
clean checkout. Check `git status --short`, branch, HEAD and origin. Update
the version/changelog together and review the custom license and dependency
advisories. Finish the applicable [M12 gates](../task.md); the wrapper alone
is not a release-quality certification.
2. Run all [workspace gates](../AGENTS.md#verification), including default,
portable and optional-backend builds described in [build.md](build.md).
Jenkins currently exercises the portable FreeBSD subset by default, not
the complete Linux application.
3. Run `python3 scripts/test-release.py`, `sh -n release.sh` and
`shellcheck -s sh release.sh` when available. Tests use only fake tokens and
a fake publisher; they never contact Gitea.
4. Check the expected local and remote tag without changing either:
`git show-ref --verify refs/tags/v0.1.0-rc.1` and
`git ls-remote --tags origin refs/tags/v0.1.0-rc.1 'refs/tags/v0.1.0-rc.1^{}'`.
Before publication both must resolve to the intended HEAD. Creating/pushing
the tag is a separate authorized step, not part of the wrapper.
5. Run the dry run with the real token file. It must report the contract above
and no metadata/prerequisite errors. Independently inspect the Gitea
`/api/v1/repos/MadGobblins/fader_master/releases/tags/v0.1.0-rc.1` endpoint.
A confirmed 404 means absent only when the repository is accessible; do not
treat authentication/network/server failures as absence.
6. If a release exists, inspect draft/prerelease status and **all asset names**,
including `SHA256SUMS`. Any planned-name collision blocks publication.
Existing releases without collisions can be reused after review. Never use
`--replace-assets` without explicit approval of the exact assets; replacement
is not transactional. Recheck remote tags/releases immediately before a
separately authorized live run.
7. Run `--compile-only`, inspect the resulting ignored `dist/release-*/`
directory, run `sha256sum -c SHA256SUMS` there, inspect `tar -tzf` for the
documented archive layout and `file`/`readelf -d` on all executables. Verify
their runtime dependencies and smoke-test on a clean supported Linux system.
Public cargo-binstall/download verification is required after publication.
## Preparation audit — 2026-10-16
Discovery HEAD: `8add95df3f52b2cb3a7bed679f3b28bf48801d47`, branch `main`.
Pre-existing changes to `examples/profiles/arch-pipewire.toml` were preserved.
Git 2.56.0, Cargo 1.88.0, rust_realease 0.1.3, Cross 0.2.5,
cargo-binstall 1.24.0 and Podman 6.1.3 were found. Podman works outside the
filesystem sandbox. ShellCheck was unavailable.
The repository API returned 200/public, the release-by-tag API returned 404,
and neither local nor remote `v0.1.0` existed. No assets/collisions were found;
these are point-in-time observations, not permission to publish later.
The configured dry run resolves all three binaries, valid binstall metadata,
the GNU/Linux assets and the correct HTTPS destination. It remains blocked by
the installed publisher rejecting `pre-build` and the absent tag. No real token
file was supplied, so authenticated wrapper verification remains outstanding.
Packaging/checksum/archive qualification is blocked by publisher compatibility.
No tool was upgraded and nothing was tagged, pushed or published.
### Release-candidate follow-up
The workspace and lockfile now identify `0.1.0-rc.1`; the wrapper automatically
marks it as a prerelease. The RC release API returned 404 and the remote RC tag
was absent at preparation time. Publication is pending: the supplied token
file was not found, and the installed publisher still needs upgrading for
Cross `pre-build` support. Existing local profile edits must stay out of the
release; use a clean checkout of the RC tag when packaging and publishing.
### Published RC build
Published on 2026-10-16: [v0.1.0-rc.1](https://proxy.dandaedre.com/gitea/MadGobblins/fader_master/releases/tag/v0.1.0-rc.1),
marked prerelease, not draft. Source commit:
`50d3097ff69f0cd3ec0ef15a0b74aa51d9c07de6`. The existing remote tag was verified
and was not moved. User profile edits were excluded using a clean worktree.
Publisher source commit: `ed2ce6e86cab274d8f1350701605a3d0c6e2ac34`, built
temporarily without replacing the globally installed publisher. Its native
pre-build regression test passed. The original Cross image reached linking
but lacked ALSA's `snd_seq_client_info_get_card`. The successful packaging and
publication commands used this explicit override without changing tagged code:
```sh
export CROSS_TARGET_X86_64_UNKNOWN_LINUX_GNU_IMAGE=ghcr.io/cross-rs/x86_64-unknown-linux-gnu@sha256:5e4193b02eaf85b64ae1545ceb942f380284a9760c005a6d04805af5221ee669
```
This image is Ubuntu 24.04 based; older Linux distributions are not qualified
for these artifacts. Recipient systems need the runtime libraries listed
above. Rust remained pinned to 1.88.0 with the tagged Cargo.lock.
Authenticated preview and compile-only packaging passed. The archive contains
exactly the three executables; all four artifact checksums passed locally and
all three binaries ran `--help` successfully without audio side effects.
Publication uploaded those four artifacts plus `SHA256SUMS`. The publisher
downloaded and verified every asset anonymously, checked archive layout, and
completed an isolated cargo-binstall installation for x86-64 GNU/Linux.
The API confirmed `prerelease = true`, `draft = false` and the five assets.
No existing assets were replaced. Real hardware qualification remains pending.