build(M12.4): prepare guarded Gitea release wrapper

Add token-file wrapper, Cargo-resolved version handling, GNU/Linux Cross configuration, binstall metadata, offline tests and release contract/audit. Preserve user profile edits; do not tag or publish.

Validation: 8 wrapper tests, sh -n, CI script tests, git diff --check, cargo fmt, workspace all-target/all-feature check and tests, doc tests, strict Clippy, release build, default/no-default builds, portable build and independent MIDI/Pulse checks passed. Two real-audio tests remain opt-in. ShellCheck unavailable.

Real publisher dry run confirms metadata/assets/destination but fails: installed rust_realease 0.1.3 rejects Cross pre-build and v0.1.0 tag is absent. Compile-only is blocked by pre-build support. No real token supplied; authenticated preview and artifact qualification remain pending. Public release API returned 404; no local/remote tag or assets exist.
This commit is contained in:
Dandaedre 2026-10-16 19:59:16 +02:00
parent 8add95df3f
commit ff84f167ab
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
12 changed files with 356 additions and 1 deletions

1
.gitignore vendored
View File

@ -8,6 +8,7 @@ target/
# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
# CI-generated badge files, markers, and coverage reports.
/coverage/
/dist/
# These are backup files generated by rustfmt
**/*.rs.bk

16
CHANGELOG.md Normal file
View File

@ -0,0 +1,16 @@
# Changelog
## 0.1.0 — pending release
Initial release preparation; no release date or published artifacts yet.
- Linux MIDI control of application, group and default-output volume through
PulseAudio or pipewire-pulse, with MIDI learn, pickup and mute feedback.
- Combined launcher plus separate server and client executables; reconnecting
TUI, managed profiles, safe first-run setup and persisted editing.
- Horizontal and vertical mixers, themes, configurable fader sizes,
separators/spacers, hidden faders and pickup status presentation.
Known limits: native PipeWire and runtime relative groups are unfinished.
Hardware coverage, Linux CI provisioning and the remaining M12 release gates
must still be completed; see [the backlog](task.md).

View File

@ -7,7 +7,7 @@ version = "0.1.0"
edition = "2024"
rust-version = "1.88"
license-file = "LICENSE"
repository = "https://git.dandaedre.com/MadGobblins/fader_master"
repository = "https://proxy.dandaedre.com/gitea/MadGobblins/fader_master"
publish = false
[workspace.dependencies]

6
Cross.toml Normal file
View File

@ -0,0 +1,6 @@
[build.env]
passthrough = ["RUSTUP_TOOLCHAIN"]
[target.x86_64-unknown-linux-gnu]
image = "ghcr.io/cross-rs/x86_64-unknown-linux-gnu:0.2.5"
pre-build = ["apt-get update && apt-get install --assume-yes --no-install-recommends pkg-config libasound2-dev libpulse-dev libudev-dev"]

View File

@ -10,6 +10,14 @@ Native PipeWire, runtime relative groups, and the unchecked acceptance work in
## Foundation and implementation history
Release preparation uses a project-local POSIX wrapper around `rust_realease`,
with Cargo metadata as the version authority and an exact SSH-to-public-HTTPS
repository mapping. The initial artifact target is x86-64 GNU/Linux because
the executable requires native ALSA, Pulse and udev libraries. All three binary
entry points share one archive; standalone downloads are also planned. Cross
supplies native build prerequisites; publication remains a separate explicit
operation. See [release contract and outstanding qualification](docs/releasing.md).
The following foundation notes describe the original milestone boundaries;
the runtime and UI contracts later in this document describe the current system.

View File

@ -24,6 +24,8 @@ profile switching, MIDI devices, and Save. See the
- [MIDI identity design](midi-identity.md)
- [Pulse-compatible daemon fixture](pulse-daemon-fixture.md)
- [CI coverage and badge lifecycle](ci-coverage.md)
- [Release preparation and publication](releasing.md)
- [Changelog](../CHANGELOG.md)
## Ecosystem

140
docs/releasing.md Normal file
View File

@ -0,0 +1,140 @@
# 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`, expected tag `v0.1.0`. 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.tgz`, containing
a directory of the same stem with all three executables. Raw names are
`<binary>-x86_64-unknown-linux-gnu-v0.1.0`.
- 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`.
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
```
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](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. 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` and
`git ls-remote --tags origin refs/tags/v0.1.0 'refs/tags/v0.1.0^{}'`.
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` 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.

View File

@ -8,6 +8,11 @@ repository.workspace = true
publish.workspace = true
default-run = "fader_master"
[package.metadata.binstall]
pkg-url = "{ repo }/releases/download/v{ version }/{ name }-{ target }-v{ version }.tgz"
pkg-fmt = "tgz"
bin-dir = "{ name }-{ target }-v{ version }/{ bin }{ binary-ext }"
[dependencies]
anyhow.workspace = true
clap.workspace = true

38
release.sh Executable file
View File

@ -0,0 +1,38 @@
#!/bin/sh
set -eu
fail() {
echo "$*" >&2
exit 2
}
[ "$#" -ge 1 ] || fail "usage: $0 <gitea-token-file> [rust_realease options...]"
token_file=$1
shift
[ -f "$token_file" ] && [ -r "$token_file" ] || fail "token file must be a readable regular file"
for tool in rust_realease cargo jq; do
command -v "$tool" >/dev/null 2>&1 || fail "$tool is not installed or not available in PATH"
done
unset GITEA_TOKEN
GITEA_TOKEN=
IFS= read -r GITEA_TOKEN <"$token_file" || :
[ -n "$GITEA_TOKEN" ] || fail "token file has an empty first line"
repository_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
# Query the member's resolved version, including workspace inheritance. Keep the
# token unexported until Cargo has finished; it belongs only to the publisher.
metadata=$(cargo metadata --offline --no-deps --format-version 1 \
--manifest-path "$repository_dir/Cargo.toml") || fail "could not read Cargo metadata"
manifest_version=$(printf '%s\n' "$metadata" | jq -er \
'[.packages[] | select(.name == "fader_master") | .version] |
if length == 1 and (.[0] | type == "string" and length > 0)
then .[0] else error("unresolved package version") end') \
|| fail "could not determine fader_master package version"
set -- "$repository_dir" --package fader_master --artifact-format both "$@"
case "$manifest_version" in
*-*) set -- "$@" --prerelease ;;
esac
export GITEA_TOKEN
exec rust_realease "$@"

14
rust-release.toml Normal file
View File

@ -0,0 +1,14 @@
[release]
tag-prefix = "v"
[build]
targets = ["x86_64-unknown-linux-gnu"]
profile = "release"
locked = true
[package]
format = "both"
[[repository.fallbacks]]
origin = "git@git.dandaedre.com:MadGobblins/fader_master.git"
fallback-url = "https://proxy.dandaedre.com/gitea/MadGobblins/fader_master"

121
scripts/test-release.py Normal file
View File

@ -0,0 +1,121 @@
#!/usr/bin/env python3
"""Offline contract tests: never invoke the real publisher or use real tokens."""
import os
from pathlib import Path
import shutil
import subprocess
import tempfile
import unittest
ROOT = Path(__file__).resolve().parents[1]
class ReleaseWrapper(unittest.TestCase):
def setUp(self):
self.temp = tempfile.TemporaryDirectory(prefix="fader release tests ")
self.addCleanup(self.temp.cleanup)
self.base = Path(self.temp.name)
self.repo = self.base / "repository with spaces"
self.repo.mkdir()
shutil.copy(ROOT / "release.sh", self.repo)
shutil.copy(ROOT / "rust-release.toml", self.repo)
self.bin = self.base / "bin"
self.bin.mkdir()
# Restricted PATH also makes the missing-publisher case deterministic.
for command in ("dirname", "jq"):
(self.bin / command).symlink_to(shutil.which(command))
self.script("cargo", '''#!/bin/sh
test "${GITEA_TOKEN+x}" != x || exit 98
test "$*" = "metadata --offline --no-deps --format-version 1 --manifest-path $EXPECTED_REPO/Cargo.toml" || exit 99
printf '{"packages":[{"name":"fader_master","version":"%s"}]}\n' "$TEST_VERSION"
''')
self.script("rust_realease", '''#!/bin/sh
test "$GITEA_TOKEN" = "fixture-secret" || exit 91
test "$1" = "$EXPECTED_REPO" || exit 92
test "$2" = --package && test "$3" = fader_master || exit 93
test "$4" = --artifact-format && test "$5" = both || exit 94
test -f "$1/rust-release.toml" || exit 95
shift 5
printf '<%s>\n' "$@"
exit "$TEST_EXIT"
''')
self.token = self.base / "token with spaces"
self.token.write_text("fixture-secret\nignored second line\n")
self.env = dict(os.environ, PATH=str(self.bin), EXPECTED_REPO=str(self.repo),
TEST_VERSION="0.1.0", TEST_EXIT="0", GITEA_TOKEN="inherited-token")
def script(self, name, content):
path = self.bin / name
path.write_text(content)
path.chmod(0o755)
def run_wrapper(self, *args):
result = subprocess.run(["/bin/sh", str(self.repo / "release.sh"), *map(str, args)],
cwd=self.base, env=self.env, text=True, capture_output=True)
self.assertNotIn("fixture-secret", result.stdout + result.stderr)
return result
def test_stable_and_exact_forwarding(self):
result = self.run_wrapper(self.token, "--dry-run", "option with spaces", "*literal*")
self.assertEqual(result.returncode, 0, result.stderr)
self.assertEqual(result.stdout, "<--dry-run>\n<option with spaces>\n<*literal*>\n")
def test_prerelease_and_exit_status(self):
self.env.update(TEST_VERSION="0.2.0-rc.1", TEST_EXIT="37")
result = self.run_wrapper(self.token, "--dry-run")
self.assertEqual(result.returncode, 37)
self.assertEqual(result.stdout, "<--dry-run>\n<--prerelease>\n")
def test_invalid_token(self):
self.assertEqual(self.run_wrapper().returncode, 2)
self.assertEqual(self.run_wrapper(self.base / "missing").returncode, 2)
self.assertEqual(self.run_wrapper(self.base).returncode, 2)
self.token.write_text("")
self.assertEqual(self.run_wrapper(self.token).returncode, 2)
self.token.write_text("\nsecond line")
self.assertEqual(self.run_wrapper(self.token).returncode, 2)
self.token.write_text("fixture-secret")
self.token.chmod(0)
if os.geteuid() != 0:
self.assertEqual(self.run_wrapper(self.token).returncode, 2)
def test_no_trailing_newline(self):
self.token.write_text("fixture-secret")
self.assertEqual(self.run_wrapper(self.token, "--dry-run").returncode, 0)
def test_missing_publisher(self):
(self.bin / "rust_realease").unlink()
self.assertEqual(self.run_wrapper(self.token).returncode, 2)
def test_unresolved_version(self):
self.env["TEST_VERSION"] = ""
self.assertEqual(self.run_wrapper(self.token).returncode, 2)
self.script("cargo", "#!/bin/sh\nexit 1\n")
self.assertEqual(self.run_wrapper(self.token).returncode, 2)
def test_fallback_does_not_change_origin(self):
git = shutil.which("git")
subprocess.run([git, "init", "-q", self.repo], check=True)
origin = "git@git.dandaedre.com:MadGobblins/fader_master.git"
subprocess.run([git, "-C", self.repo, "remote", "add", "origin", origin], check=True)
self.assertEqual(self.run_wrapper(self.token, "--dry-run").returncode, 0)
actual = subprocess.check_output([git, "-C", self.repo, "remote", "get-url", "origin"], text=True)
self.assertEqual(actual.strip(), origin)
config = (self.repo / "rust-release.toml").read_text()
self.assertIn('origin = "' + origin + '"', config)
self.assertIn('fallback-url = "https://proxy.dandaedre.com/gitea/MadGobblins/fader_master"', config)
def test_real_workspace_version_query(self):
(self.bin / "cargo").unlink()
env = dict(self.env, PATH=str(self.bin) + os.pathsep + os.environ["PATH"],
EXPECTED_REPO=str(ROOT))
result = subprocess.run([str(ROOT / "release.sh"), str(self.token), "--dry-run"],
cwd=self.base, env=env, text=True, capture_output=True)
self.assertEqual(result.returncode, 0, result.stderr)
self.assertEqual(result.stdout, "<--dry-run>\n")
self.assertNotIn("fixture-secret", result.stdout + result.stderr)
if __name__ == "__main__":
unittest.main()

View File

@ -512,6 +512,10 @@ Dependencies: all required feature milestones; hardware-only ALSA remains an exp
existing MIDI Learn workflow without editing TOML. Config also repairs legacy
empty profiles by offering a safe Master-output fader.
- [ ] **M12.4 Release gates:** all workspace/default/feature/MSRV checks, reproducible lockfile, license review and dependency advisory review using maintained tooling selected at implementation time. Measure/control latency under multi-surface load and publish the tested envelope.
Release wrapper, offline contract tests, binstall metadata and an explicit
x86-64 GNU/Linux artifact configuration are prepared. Publisher compatibility,
authenticated dry run, Cross artifact qualification and the remaining release
criteria are still outstanding; see [release preparation](docs/releasing.md).
## User requirement coverage