# 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 `-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.