fader_master/docs/releasing.md

12 KiB

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.2, expected tag v0.1.0-rc.2. Keep CHANGELOG 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.2.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.2.
  • Public Gitea repository: MadGobblins/fader_master. Release URL: https://proxy.dandaedre.com/gitea/MadGobblins/fader_master/releases/tag/v0.1.0-rc.2. Development origin: git@git.dandaedre.com:MadGobblins/fader_master.git. The exact mapping in 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, 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:

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.

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. 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).

./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:

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; the wrapper alone is not a release-quality certification.
  2. Run all workspace gates, including default, portable and optional-backend builds described in 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.2 and git ls-remote --tags origin refs/tags/v0.1.0-rc.2 'refs/tags/v0.1.0-rc.2^{}'. 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.2 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, 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:

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.

Published RC2 build

Published on 2026-10-18: v0.1.0-rc.2, marked prerelease, not draft. Source commit: 8ac222b501cb5bc4fbd5fc5ec52feb4a94301039; main and the annotated tag were pushed before packaging. The publisher was built temporarily from the same ed2ce6e fix and used the same digest-pinned Ubuntu 24.04 Cross image documented above. No globally installed publisher was replaced.

All workspace formatting/check/Clippy/doctest/release gates, default/no-default tests and independent MIDI/Pulse feature tests passed on Rust 1.88.0. The four old Arch fixture assertions were aligned with the committed example bindings. All eight release-wrapper tests passed; ShellCheck was unavailable. Two hardware tests remain opt-in, and the outstanding M12 qualifications remain open.

Authenticated preview and compile-only packaging passed. Local checks verified all checksums, the three-binary archive, runtime dependencies and CLI smoke tests. Publication reused that completed source build and uploaded three binaries, the archive and SHA256SUMS, without replacing assets. The publisher verified all public downloads/checksums, archive layout and an isolated cargo-binstall installation. The public API confirmed all five assets, prerelease = true and draft = false. Restart both server and client when upgrading.