183 lines
10 KiB
Markdown
183 lines
10 KiB
Markdown
# 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
|
|
`<binary>-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.
|