From ff84f167abd6d21e08342f9e4a2d7570018ffee6 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Fri, 16 Oct 2026 19:59:16 +0200 Subject: [PATCH] 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. --- .gitignore | 1 + CHANGELOG.md | 16 +++++ Cargo.toml | 2 +- Cross.toml | 6 ++ architecture.md | 8 +++ docs/README.md | 2 + docs/releasing.md | 140 ++++++++++++++++++++++++++++++++++++++++ fader_master/Cargo.toml | 5 ++ release.sh | 38 +++++++++++ rust-release.toml | 14 ++++ scripts/test-release.py | 121 ++++++++++++++++++++++++++++++++++ task.md | 4 ++ 12 files changed, 356 insertions(+), 1 deletion(-) create mode 100644 CHANGELOG.md create mode 100644 Cross.toml create mode 100644 docs/releasing.md create mode 100755 release.sh create mode 100644 rust-release.toml create mode 100644 scripts/test-release.py diff --git a/.gitignore b/.gitignore index 30996ea..613e6b2 100644 --- a/.gitignore +++ b/.gitignore @@ -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 diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..546c54e --- /dev/null +++ b/CHANGELOG.md @@ -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). diff --git a/Cargo.toml b/Cargo.toml index 94be40f..126315e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -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] diff --git a/Cross.toml b/Cross.toml new file mode 100644 index 0000000..fa9fc7a --- /dev/null +++ b/Cross.toml @@ -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"] diff --git a/architecture.md b/architecture.md index 4aec5e9..46050f4 100644 --- a/architecture.md +++ b/architecture.md @@ -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. diff --git a/docs/README.md b/docs/README.md index 1df2ee3..b5657c0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 diff --git a/docs/releasing.md b/docs/releasing.md new file mode 100644 index 0000000..557c768 --- /dev/null +++ b/docs/releasing.md @@ -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 + `-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. diff --git a/fader_master/Cargo.toml b/fader_master/Cargo.toml index b16f6a0..242b168 100644 --- a/fader_master/Cargo.toml +++ b/fader_master/Cargo.toml @@ -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 diff --git a/release.sh b/release.sh new file mode 100755 index 0000000..54703c6 --- /dev/null +++ b/release.sh @@ -0,0 +1,38 @@ +#!/bin/sh +set -eu + +fail() { + echo "$*" >&2 + exit 2 +} + +[ "$#" -ge 1 ] || fail "usage: $0 [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 "$@" diff --git a/rust-release.toml b/rust-release.toml new file mode 100644 index 0000000..d613853 --- /dev/null +++ b/rust-release.toml @@ -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" diff --git a/scripts/test-release.py b/scripts/test-release.py new file mode 100644 index 0000000..620f818 --- /dev/null +++ b/scripts/test-release.py @@ -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