10 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 binariesfader_master,fader_master_client, andfader_master_server(all included together). - Version: inherited from
[workspace.package].versionin the root manifest; currently0.1.0-rc.2, expected tagv0.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
.tgzarchives and standalone binaries, plusSHA256SUMS. 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. Usecargo binstall --git https://proxy.dandaedre.com/gitea/MadGobblins/fader_master fader_masteronly 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
- 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. - 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.
- Run
python3 scripts/test-release.py,sh -n release.shandshellcheck -s sh release.shwhen available. Tests use only fake tokens and a fake publisher; they never contact Gitea. - Check the expected local and remote tag without changing either:
git show-ref --verify refs/tags/v0.1.0-rc.2andgit 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. - 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.2endpoint. A confirmed 404 means absent only when the repository is accessible; do not treat authentication/network/server failures as absence. - 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-assetswithout explicit approval of the exact assets; replacement is not transactional. Recheck remote tags/releases immediately before a separately authorized live run. - Run
--compile-only, inspect the resulting ignoreddist/release-*/directory, runsha256sum -c SHA256SUMSthere, inspecttar -tzffor the documented archive layout andfile/readelf -don 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.