fader_master/docs/releasing.md

8.4 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.1, expected tag v0.1.0-rc.1. 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.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. 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 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

The installed 0.1.3 rejects Cross pre-build; it cannot build this release. Upstream 0.1.6-rc.2 documents support for native prerequisites, but has not been installed or qualified here. Select a publisher supporting pre-build and 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. 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.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.