# slskr Release Runbook This is the release-prep path for binary archives. `slskr` is a single Rust binary plus the production React/Vite Web UI assets staged as `web/build`. ## Local Gate ```sh scripts/run-release-gate.sh ``` This runs public-posture checks, shell syntax checks, Rust formatting, clippy, workspace tests, RustSec audit when `cargo-audit` is installed, workspace packaging, web tests, Rust/WASM web checks, the Rust web UI headless parity audit, and subpath smoke checks. GitHub CI and tagged release workflows check the cached `cargo-audit` version, install the pinned version when it is missing or stale, and add its bin directory to `PATH` before running the RustSec audit. The versioned cache key includes a schema revision so a repaired executable can be saved separately from older immutable entries. Local runs may skip the audit when the tool is not installed. All compile-capable Cargo commands in this repository use the normal Rust toolchain. The workspace config keeps the large daemon crate on one Cargo job, turns off unnecessary dev debug metadata, and uses 16 codegen units with ThinLTO for release builds: ```sh cargo build --release -p slskr cargo test --workspace ``` Rust formatting uses `scripts/check-rust-format.sh`, which checks changed source files individually and compares emitted output locally rather than asking rustfmt to construct the monolithic controller's full diff. The `slskr` package defaults to its focused controller-test target. The historical monolithic controller suite remains an explicit opt-in with `--features full-controller-tests`; the default workspace test path keeps that large proof module out of ordinary edit/test cycles. Browser and frontend Node subprocesses in the parity and release gates use `scripts/with-process-memory-guard.sh`; Rust commands do not. This keeps the non-Rust browser tooling bounded without imposing its smaller process cap on LLVM. The live slskd automation-client compatibility smoke is opt-in because it starts a local daemon and may install the Python `slskd-api` package: ```sh SLSKR_RUN_SLSKD_API_COMPAT_SMOKE=1 scripts/run-release-gate.sh ``` CI also runs a lighter scheduled/manual `Live Parity` workflow. That workflow executes the Rust web UI headless parity audit and the hermetic local `slskd_api` automation compatibility smoke, then uploads the Rust UI screenshots, web bundle, and daemon log as artifacts. The same workflow also has an optional credentialed public-live job: when the `SLSKR_LIVE_INTEROP_ENV` repository secret contains the same env-file variables used by `scripts/run-live-interop-matrix.sh`, CI runs login, local peer, private-message, and room-message probes and uploads `target/live-interop`; when the secret is absent, it uploads an explicit skipped TSV artifact. The daily/manual `React Nightly Audit` runs the React UI against deterministic mock responses and retains browser reports, screenshots, and source-bound receipts for 30 days. It verifies desktop/mobile rendering and four workflow scenarios; deployed-device and credentialed interop evidence are separate. To validate a released Chocolatey package on a clean Windows runner without publishing it, dispatch the existing workflow with `publish=false`: ```sh tag="$(git describe --tags --match 'v*' --match 'release-v*' --abbrev=0)" gh workflow run publish-chocolatey.yml --ref main -f tag="$tag" -f publish=false ``` The command selects the newest release tag reachable from the current checkout; set `tag` directly to inspect another release. The workflow verifies the downloaded release asset against `SHA256SUMS.txt`, packs and checks the nupkg, and retains the package and a source-bound receipt for 30 days. The default `publish=true` preserves the manual publication flow and requires configured credentials. ## Local Archive Build the host archive: ```sh scripts/build-release-archive.sh --version dev-local scripts/verify-release-artifacts.sh target/dist ``` The archive includes: - `slskr` or `slskr.exe` - `web/build` with `index.html`, hashed JavaScript/CSS assets, icons, and the web app manifest - `README.md`, `LICENSE`, `NOTICE`, `COMPLIANCE.md` - `docs/slskr.config.example.toml` - `RUN.txt` Release archive builds normalize `SLSKR_RELEASE_VERSION` and embed it as the application version while internal Cargo crates remain at `0.0.0`. The archive verifier checks `slskr version` on a matching host platform and verifies the archive contents without attempting to execute a foreign-platform binary. ## Release notes and changelog User-facing, security, operational, and user-facing documentation changes add one new validated fragment under `release-notes/`. The validation workflow requires that fragment or an explicit internal-only selection, and fragments are append-only. Each fragment records its category, audience, product area, required action, and breaking-change status. Preview the grouped release text locally with: ```sh python3 scripts/release_notes.py preview --base --head ``` The tag workflow publishes a concise curated body as `release/RELEASE_NOTES.md` and sends that same summary in the Discord embed. It also uploads the complete machine-validated fragment assembly as `release/RELEASE_NOTES_FULL.md`, keeping the release page readable without discarding detailed change history. The validation job exposes a separate capture-metadata table so the source fragment fields remain auditable. Keep `CHANGELOG.md` append-only at the release-section level and move shipped `## [Unreleased]` bullets into a dated section when preparing a release; the CI and tag workflows reject a missing or placeholder section. ## CI and release matrix The `CI` workflow is started with a manual dispatch using `action_tag=test` and `runner_pool_tag=hosted`. For a release, dispatch it on the release tag and wait for the exact-tag, exact-commit run to pass. Each matrix job builds a target archive, verifies its checksum and layout, and uploads the archive for seven days so a platform-specific build can be downloaded for testing. Native workspace tests run on Linux x64, Linux AArch64, both macOS architectures, and Windows; the additional musl jobs smoke test their built static binary through the same archive verifier. Source-only release and packaging policy runs first, before compilation. Run `scripts/check-release-preflight.sh` locally before creating a candidate tag; it checks both workflow policy and artifact-matrix policy, including immutable tag provenance, and runs the metadata and announcement regression tests. The independently dispatched `release-preflight.yml` workflow checks the same preflight on a clean hosted runner, installing ripgrep, Git, and Python explicitly. The release workflow uses the same native runner and target mapping: | Target | CI and release runner | Rust target | CI exercise | | --- | --- | --- | --- | | `linux-x64` | `ubuntu-24.04` | `x86_64-unknown-linux-gnu` | Full Linux tests and archive smoke | | `linux-musl-x64` | `ubuntu-24.04` | `x86_64-unknown-linux-musl` | Static archive build and smoke | | `linux-arm64` | `ubuntu-24.04-arm` | `aarch64-unknown-linux-gnu` | Full AArch64 tests and archive smoke | | `linux-musl-arm64` | `ubuntu-24.04-arm` | `aarch64-unknown-linux-musl` | Static archive build and smoke | | `macos-x64` | `macos-15-intel` | `x86_64-apple-darwin` | Native workspace tests and archive smoke | | `macos-arm64` | `macos-15` | `aarch64-apple-darwin` | Native workspace tests and archive smoke | | `windows-x64` | `windows-latest` | `x86_64-pc-windows-msvc` | Native workspace tests and archive smoke | Create and push a version tag named: ```text v ``` Use `v`, for example `v1.2.3` or `v1.2.3-rc.1`. Existing `release-v` tags remain supported for compatibility. Commits pushed to `main` do not start CI or release workflows. After the tag exists, manually dispatch CI on that tag with `action_tag=test` and `runner_pool_tag=hosted`. Once that exact run succeeds, manually dispatch Release on the same tag with `action_tag=release`, `runner_pool_tag=hosted`, and the identical `tag` input. The release workflow checks the selected ref, requested tag, and successful hosted CI result before publishing. Use a tag pointing to the reviewed `main` commit. For a release build, the workflow creates a GitHub Release and uploads all archives plus `SHA256SUMS.txt`, `slskr-cyclonedx.json`, and `slskr-dependency-manifest.json`. The JSON manifests are included in the release checksum file and build-provenance attestation subjects. After GitHub publication, the workflow immediately calls `announce-release.yml` with `DISCORD_RELEASE_WEBHOOK_URL` for the project channel and `DISCORD_CHANGELOG_WEBHOOK` for the shared #changelogs channel. The job verifies the published release, confirms the complete notes in #changelogs, and posts a link in the project channel. Delivery artifacts retain confirmed Discord message links. If the shared secret is absent, delivery uses the existing project webhook. If an announcement was skipped after a publishing recovery, first check the original announcement job and any delivery receipt to avoid duplicate posts. Then announce the existing release from `main` without rebuilding packages: ```sh gh workflow run announce-release.yml --ref main -f tag=v0.2.82 ``` The manual path accepts only a published release and runs from `main`. A network timeout can leave delivery uncertain; inspect the channel before retrying. The sender does not automatically retry message creation. The internal/unpublished Cargo crates intentionally remain at `0.0.0`. Binary and archive version metadata comes from the release workflow. Tag builds derive the artifact version from `v` (or a legacy `release-v` tag), and local/manual archive tests can still pass `SLSKR_RELEASE_VERSION` directly to `scripts/build-release-archive.sh`. Archive roots are named `slskr--` so the published package version remains tied to the release input even though the workspace crates are not published independently. ### Required completion The `Require Complete Release` job runs even when dependencies fail or are skipped. Every native build, release gate, GitHub publication, downstream publication, and Discord announcement must succeed. Missing publisher credentials fail preflight. Submission receipts alone do not prove that asynchronous repositories published: verify COPR builds, Launchpad binary publication, registry tags, package metadata, and external package validation before reporting completion. The called public publication check waits for all COPR native builds and public RPM indexes, Launchpad binaries and apt indexes, merged Winget manifests with the archive hash, the requested version in the public WinGet client catalog, and Chocolatey approval before full distribution can be reported complete. Discord announces the published GitHub release independently of downstream package publication. The receipt distinguishes actual publication from authorized pending exceptions. It waits at most one hour; retry failed verification after external publication catches up without rebuilding. Snap is excluded by owner instruction. The owner also directed that Chocolatey's first-package review be left alone, without moderator contact or repeated uploads. For that pending exception, dispatch Release with `defer_chocolatey_initial_review=true`. The package is still prepared and retained; the publisher observes the first package's approval status and makes no upload while it remains unapproved. The availability receipt reports Chocolatey as pending, with `complete: false`, and release notes disclose the exception. The exception defaults to false. On later runs it no longer applies once the first package is approved. All other configured channels remain required. For a read-only recovery check, dispatch `verify-release-publication.yml` from main with the original tag. Set `allow_chocolatey_initial_review=true` only under the same owner authorization. This workflow never uploads or sends messages. The live checker uses the hash-locked dependencies in `scripts/requirements-publication.txt`; the workflow installs them in its own temporary virtual environment. Fixture tests require only the standard library. The WinGet check reads Microsoft's `source2.msix` client index as a bounded, read-only SQLite database. A merged GitHub manifest alone does not prove that WinGet clients can discover the new version. ### Winget fork recovery The Winget publisher creates a new release branch whose parent is the Microsoft upstream commit and whose tree changes only the three package manifests. It uses canonical repository URLs for authenticated writes and reuses an existing PR only when its manifest contents match. It does not reset the fork's default branch. Run `pwsh -NoProfile -File scripts/test-submit-winget-release.ps1` to exercise canonical writes, upstream ancestry, idempotency, and refusal to overwrite mismatched published content. The publisher runs this test before submitting. For operator recovery with an existing authenticated GitHub CLI session, run `pwsh -NoProfile -File scripts/submit-winget-release.ps1 -SubmitPath packaging/winget -PackageVersion -UseGhCli` after generating metadata from verified release assets. This uses the existing CLI authentication directly; it does not export or copy that credential into Actions. A matching Actions retry can confirm the existing PR without creating another one. Manual metadata recovery uses its selected main workflow revision and resolves package URLs and source provenance from the original immutable release tag. ### Chocolatey upload recovery If upload fails after validation, reuse the saved package instead of rebuilding: `gh workflow run retry-chocolatey.yml --ref main -f tag=v -f validation_run_id=`. Recovery accepts only a completed manual run of `publish-chocolatey.yml` from main, checks the receipt, immutable source tag, package hash, and published checksum manifest, then attempts one upload and retains its redacted HTTP response. HTTP 403 can indicate a moderation limit as well as invalid credentials; inspect the actual response before changing keys. Do not bypass repository moderation. Chocolatey is a required called job of the full release workflow. A publication failure blocks the final completion gate. It does not block the GitHub release's Discord announcement. The standalone manual path remains available for validation and recovery; full releases always pass `publish: true` and fail if publication credentials are missing. Starting with 0.2.84, portable Windows archives use static CRT linkage while retaining the configured 16 MiB stack reserve. `scripts/check-windows-runtime.py` reads PE imports and rejects undeclared Visual C++ redistributable dependencies. Archive verification runs this check even when inspecting Windows artifacts from another OS; native Windows smoke also executes the resulting binary. This packaging check does not replace Microsoft Defender or external catalog validation. Legacy Windows package metadata declares the required Visual C++ redistributable for versions before 0.2.84; their original archives and checksums remain unchanged.