From 8f9059aefff359150e2507c1c3ef1639d02d67d9 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Sun, 4 Oct 2026 22:40:49 +0200 Subject: [PATCH] feat: add project-local rust_realease wrapper and release policy --- .gitignore | 3 + Cargo.toml | 7 ++ README.md | 1 + docs/README.md | 2 + docs/releases.md | 173 ++++++++++++++++++++++++++++++++++++++++ release.sh | 60 ++++++++++++++ rust-release.toml | 18 +++++ scripts/test-release.py | 147 ++++++++++++++++++++++++++++++++++ 8 files changed, 411 insertions(+) create mode 100644 docs/releases.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 1003552..d4f035b 100644 --- a/.gitignore +++ b/.gitignore @@ -21,3 +21,6 @@ config.toml /coverage/ /target-ci/ + +# rust_realease artifacts and build cache +/dist/ diff --git a/Cargo.toml b/Cargo.toml index acaa495..901a665 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,6 +4,13 @@ version = "0.1.1" edition = "2021" rust-version = "1.88.0" license = "MIT" +repository = "https://proxy.dandaedre.com/gitea/idle-org/tiny-wb" + +# Release tags are unprefixed; publisher archive names retain their -v prefix. +[package.metadata.binstall] +pkg-url = "{ repo }/releases/download/{ version }/{ name }-{ target }-v{ version }.tgz" +pkg-fmt = "tgz" +bin-dir = "{ name }-{ target }-v{ version }/{ bin }{ binary-ext }" [dependencies] chrono = "0.4.38" diff --git a/README.md b/README.md index ba078bb..6c4f8b8 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ before connecting an Ultra or Ultra+. - [Documentation index](docs/README.md) — where to start and source policy - [Configuration](docs/configuration.md) — defaults, partial overrides, units, validation, and saved selections +- [Release guide](docs/releases.md) — wrapper, target/artifact policy, token handling, and publication readiness - [Testing guide](docs/testing.md) — hardware-free regression tests and test boundaries - [Project architecture](docs/architecture.md) — components, state, data flow, files, dependencies, and extension points diff --git a/docs/README.md b/docs/README.md index 9d7b377..7a63f75 100644 --- a/docs/README.md +++ b/docs/README.md @@ -48,3 +48,5 @@ grows into many chapters, the files are already organized so that a future - [Configuration](configuration.md): embedded defaults, partial overrides and persistence. - [Testing](testing.md): regression seams and hardware verification boundaries. - [Agent/contributor guidance](../AGENTS.md): code structure, comments, documentation and atomic commits. + +- [Releases](releases.md): release wrapper, prerequisites, collision checks and publication policy. diff --git a/docs/releases.md b/docs/releases.md new file mode 100644 index 0000000..66a9bcd --- /dev/null +++ b/docs/releases.md @@ -0,0 +1,173 @@ +# Releasing tiny-wb + +`release.sh` delegates to the deliberately named +[`rust_realease`](https://proxy.dandaedre.com/gitea/idle-org/rust_realease). +It is based on the +[john-slop wrapper](https://proxy.dandaedre.com/gitea/idle-org/john-slop/src/branch/main/release.sh), +with this project's package, targets, tag convention and repository mapping. +The wrapper does not edit metadata, commit, tag, push, or repair a release. +A normal invocation **does publish** through the delegated publisher; begin +with a dry run and obtain publication authorization separately. + +## Release contract + +| Property | Source/policy | +| --- | --- | +| Cargo package | `tiny-wb`, the single root package in `Cargo.toml`. | +| Binary | `tiny-wb` (`tiny-wb.exe` on Windows); the library is not a release binary. | +| Version | Literal `[package].version` in `Cargo.toml`; never duplicated in the wrapper. | +| Tag | Package version without a prefix, preserving existing tags such as `0.1.1`. | +| Profile | `release`, for both targets; the older custom `windows` profile is not selected. | +| Targets | `x86_64-unknown-linux-gnu`, `x86_64-pc-windows-gnu`. | +| Artifacts | Both cargo-binstall `.tgz` archives and standalone executables, plus `SHA256SUMS`. | +| Builds | Locked dependencies; tracked `Cargo.lock`; review toolchain/container inputs for repeatability. | +| Public repository | `https://proxy.dandaedre.com/gitea/idle-org/tiny-wb`. | +| Development origin | `git@git.dandaedre.com:idle-org/tiny-wb.git`. | +| Prerelease | A hyphen in the version before any `+build` suffix adds `--prerelease`. | + +`rust-release.toml` sets the target matrix, profile, tag prefix, lock policy, +`GITEA_TOKEN` variable and exact origin-to-public-URL fallback. This avoids +copying the publisher's musl/ARM defaults: tiny-wb uses system libudev on Linux, +and its documented desktop platforms are Linux and Windows. FreeBSD remains +a CI host, not an additional promised release artifact. Target builds are not +yet verified. Do not infer compatibility merely from the configured matrix. + +The fallback does not rewrite the Git origin. `Cargo.toml` records the public +repository and the publisher-compatible binstall archive layout. Tag URLs lack +`v`; archive names retain `-v{version}`. For example, version `0.1.1` plans: + +```text +tiny-wb-x86_64-unknown-linux-gnu-v0.1.1.tgz +tiny-wb-x86_64-unknown-linux-gnu-v0.1.1 +tiny-wb-x86_64-pc-windows-gnu-v0.1.1.tgz +tiny-wb-x86_64-pc-windows-gnu-v0.1.1.exe +SHA256SUMS +``` + +Each archive contains a matching stem directory and its one executable. +Public release/download verification and cargo-binstall checks are supported; +they remain unverified until a separately authorized real release succeeds. +Use cargo-binstall's `--git` mode for this repository rather than assuming it +is published to crates.io. This workflow does not run `cargo publish`. + +## Prerequisites + +Required: Git, Cargo/Rust (at least the declared MSRV), `rust_realease`, Cross, +and a usable Docker or Podman backend. Archives additionally need cargo-binstall +for installation verification. Local wrapper tests use Python 3.11+ (`tomllib`). +There is currently no repository pin for the publisher; the inspected upstream +source identifies itself as version 0.1.4. Confirm its installed version and +help before use. Tool installation is a maintainer action, not performed by +the wrapper. Upstream's preferred installation command is: + +```console +cargo binstall --git https://proxy.dandaedre.com/gitea/idle-org/rust_realease rust_realease +rust_realease --version +rust_realease --help +``` + +For Cross installation and image setup, follow the +[Cross project](https://github.com/cross-rs/cross). Select a working backend with +`CROSS_CONTAINER_ENGINE=podman` or `docker` when necessary. Check `cross --version`, +`cargo binstall -V`, and the selected engine's `info` command before building. + +The target images must provide the Linux target's libudev development files and +pkg-config configuration, the linker required by `.cargo/config.toml` (`lld`), +and the Windows GNU resource compiler required by `build.rs` (`windres`). Native +host compilation alone does not verify those container prerequisites. Configure +suitable prebuilt Cross images before building; the publisher rejects repository +`pre-build`, `dockerfile`, and `runner` hooks, so do not silently add install hooks. + +## Token handling and commands + +Store a token in a readable regular file outside the checkout, with only the +token on its first line; restrict its permissions to its owner. The account +needs repository read access and release write access. Do not commit tokens or +token paths. The wrapper reads the first line verbatim (also without a trailing +newline), rejects an empty first line, and exports it as `GITEA_TOKEN` only to +the publisher. It never passes the token in arguments or prints it. The publisher +is responsible for keeping it out of child builds and for download verification. + +In these examples, set `TOKEN_FILE` in your shell to the existing token file's +path; it is not a checked-in setting: + +```console +./release.sh "$TOKEN_FILE" --dry-run +./release.sh "$TOKEN_FILE" --compile-only +``` + +A dry run must report the correct package, version, unprefixed tag, both targets, +asset names and public HTTPS destination without changing files, refs or releases. +A successful dry run is required but does not replace collision inspection. +`--compile-only` builds local artifacts in ignored `dist/release-*/`, without +contacting Gitea. Inspect `SHA256SUMS`, archive members, executables and the +binstall layout before publication. + +After all readiness checks and separate publication authorization: + +```console +./release.sh "$TOKEN_FILE" +``` + +You can invoke the script by its absolute path from another working directory. +The repository resolves from the script location; relative token and forwarded +file paths remain relative to your invoking directory. Additional options are +forwarded exactly, including spaces. For example, use `--message-file` with a +reviewed release-notes file. The publisher can update an existing release body +when notes are explicitly supplied. Do not add preparation/push/replacement flags +without deliberate authorization for those operations. + +## Readiness, collisions and repeatability + +Before publication: + +1. Run the [local quality gates](security-and-ci.md#local-verification), + `python3 scripts/test-release.py`, `sh -n release.sh`, and ShellCheck when + available. Run `cargo package --locked` to verify the source package; this is + a local build/check, not registry publication. +2. Review release notes/changelog and set the intended package version. There + was no tracked changelog when this wrapper was introduced. Do not invent + historical entries or bump versions automatically. Record changes for the + next chosen version before publishing. +3. Require a clean checkout, a local unprefixed version tag at `HEAD`, and the + same tag/commit on origin. Inspect `git status --short`, `git rev-parse HEAD`, + `git rev-parse '^{commit}'`, and `git ls-remote --tags origin`. + Tag creation and pushing are separate maintainer operations; never move an + existing tag to make this check pass. +4. Inspect the release-by-tag API at + `https://proxy.dandaedre.com/gitea/api/v1/repos/idle-org/tiny-wb/releases/tags/`. + A 404 means missing; authentication, network and server errors are blockers, + not absence. Check draft/prerelease status and **all** asset names. +5. Compare the planned archive, binary and `SHA256SUMS` names to existing assets. + Any collision stops publication. `--replace-assets` requires inspection and + explicit approval to replace those exact assets; replacement is not atomic. + An existing empty release can be reused only after tag/version checks pass. +6. Run the real wrapper dry run. Resolve every prerequisite or metadata error. + Repeat tag and release/asset inspection immediately before live publication. + +The publisher normalizes archive metadata, but this is not a bit-for-bit build +reproducibility claim. Rust toolchains and Cross image digests are not pinned +here, and `build.rs` embeds a Git revision. Record those inputs per release. +Use `--recompile` if a matching publisher build cache must not be reused. + +## Inspection recorded on 2026-10-04 + +- Package and binary: `tiny-wb` 0.1.1. Expected tag: `0.1.1`, not `v0.1.1`. +- Both local and public-HTTPS remote `0.1.1` point to + `82aa266e18454905c01287035c377b8edf9f9c60`, not the current refactored checkout. + This is a publication blocker. The repository already has a later `0.1.2` + release, so choose the next version deliberately rather than retagging 0.1.1. +- The `0.1.1` release API returned HTTP 200: public, non-draft, non-prerelease, + **no assets**. None of the five planned names collide in that snapshot. + The `v0.1.1` endpoint returned 404. These checks do not authorize reuse. +- Git 2.56.0, Cargo 1.93.0, cargo-binstall 1.17.5 and Podman 6.1.3 were present. + Podman reported a usable `amd64` backend. The SSH origin query failed + (connection closed), so the remote tag was checked through the public HTTPS + Git endpoint; SSH push access remains unverified. + `rust_realease`, Cross and ShellCheck were unavailable and were not installed. + Publisher CLI/configuration and artifact names were inspected from upstream + source, not confirmed by a runnable local publisher. +- The real publisher dry run could not start (`command not found`). A real-token + wrapper dry run, Cross `--compile-only`, built-asset/checksum inspection and + cargo-binstall download verification remain **not verified**. No token file + was supplied, and no release or asset was created or replaced. diff --git a/release.sh b/release.sh new file mode 100755 index 0000000..aded7b9 --- /dev/null +++ b/release.sh @@ -0,0 +1,60 @@ +#!/bin/sh +# Project-local rust_realease entry point. See docs/releases.md before publishing. +set -eu +# Do not expose the first token-file line if a caller enables shell tracing. +set +x +unset GITEA_TOKEN + +usage() { + echo "usage: $0 [rust_realease options...]" >&2 + exit 2 +} + +[ "$#" -ge 1 ] || usage +token_file=$1 +shift + +if [ ! -f "$token_file" ] || [ ! -r "$token_file" ] || [ ! -s "$token_file" ]; then + echo "token file must be readable, regular and nonempty" >&2 + exit 2 +fi +if ! command -v rust_realease >/dev/null 2>&1; then + echo "rust_realease is not installed or not available in PATH; see docs/releases.md" >&2 + exit 2 +fi + +repository_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P) +# This repository has one root package with a literal version. Fail closed if +# it is changed to an inherited/workspace version instead of guessing a value. +manifest_version=$(awk ' + /^[[:space:]]*\[/ { package = ($0 ~ /^[[:space:]]*\[package\][[:space:]]*(#.*)?$/) } + package && /^[[:space:]]*version[[:space:]]*=[[:space:]]*"[^"]+"[[:space:]]*(#.*)?$/ { + value = $0 + sub(/^[^"]*"/, "", value) + sub(/".*$/, "", value) + count++ + } + END { + if (count != 1 || value !~ /^[0-9]+\.[0-9]+\.[0-9]+([-+][0-9A-Za-z.+-]+)?$/) exit 1 + print value + } +' "$repository_dir/Cargo.toml") || { + echo "could not determine the tiny-wb package version from Cargo.toml" >&2 + exit 2 +} + +set -- "$repository_dir" --package tiny-wb --artifact-format both "$@" +# A hyphen in build metadata alone does not make a SemVer prerelease. +case "${manifest_version%%+*}" in + *-*) set -- "$@" --prerelease ;; +esac + +# Read after subprocess-based discovery, and export only for the publisher. +GITEA_TOKEN= +IFS= read -r GITEA_TOKEN <"$token_file" || : +if [ -z "$GITEA_TOKEN" ]; then + echo "the token file's first line must not be empty" >&2 + exit 2 +fi +export GITEA_TOKEN +exec rust_realease "$@" diff --git a/rust-release.toml b/rust-release.toml new file mode 100644 index 0000000..34a3a90 --- /dev/null +++ b/rust-release.toml @@ -0,0 +1,18 @@ +# Public release policy; independent of runtime config/default.toml. +[release] +# Existing tiny-wb tags have no leading v. Do not retag historical versions. +tag-prefix = "" + +[build] +# Desktop targets. Linux uses glibc because serialport links system libudev. +# Cross images must provide target libudev/pkg-config, lld and Windows windres. +targets = ["x86_64-unknown-linux-gnu", "x86_64-pc-windows-gnu"] +profile = "release" +locked = true + +[gitea] +token-env = "GITEA_TOKEN" + +[[repository.fallbacks]] +origin = "git@git.dandaedre.com:idle-org/tiny-wb.git" +fallback-url = "https://proxy.dandaedre.com/gitea/idle-org/tiny-wb" diff --git a/scripts/test-release.py b/scripts/test-release.py new file mode 100644 index 0000000..92994de --- /dev/null +++ b/scripts/test-release.py @@ -0,0 +1,147 @@ +#!/usr/bin/env python3 +"""Exercise release.sh in disposable repositories with an inert publisher.""" + +import json +import os +from pathlib import Path +import shutil +import subprocess +import sys +import tempfile +import tomllib +import unittest + +REPO = Path(__file__).resolve().parent.parent + + +class ReleaseWrapperTests(unittest.TestCase): + def setUp(self): + self.temporary = tempfile.TemporaryDirectory(prefix='tiny-wb release ') + self.root = Path(self.temporary.name) + self.project = self.root / 'project with spaces' + self.project.mkdir() + for name in ('release.sh', 'Cargo.toml', 'rust-release.toml'): + shutil.copy2(REPO / name, self.project / name) + self.tools = self.root / 'tools' + self.tools.mkdir() + # An isolated PATH tests missing publishers without relying on the host. + for tool in ('awk', 'dirname'): + (self.tools / tool).symlink_to(shutil.which(tool)) + self.capture = self.root / 'captured.json' + self.fake = self.tools / 'rust_realease' + self.fake.write_text('#!' + sys.executable + '\n' + '''import json, os, pathlib, sys +repository = pathlib.Path(sys.argv[1]) +record = {"args": sys.argv[1:], "token": os.environ.get("GITEA_TOKEN"), + "fallback": (repository / "rust-release.toml").read_text()} +pathlib.Path(os.environ["CAPTURE"]).write_text(json.dumps(record)) +sys.exit(int(os.environ.get("PUBLISHER_EXIT", "0"))) +''') + self.fake.chmod(0o755) + self.token = self.root / 'token with spaces' + self.token.write_text('inert-test-token-123\nignored-second-line\n') + self.token.chmod(0o600) + self.env = {**os.environ, 'PATH': str(self.tools), 'CAPTURE': str(self.capture)} + self.env.pop('GITEA_TOKEN', None) + self.env.pop('PUBLISHER_EXIT', None) + subprocess.run(['git', 'init', '-q', str(self.project)], check=True) + subprocess.run(['git', '-C', str(self.project), 'remote', 'add', 'origin', + 'git@git.dandaedre.com:idle-org/tiny-wb.git'], check=True) + + def tearDown(self): + self.temporary.cleanup() + + def run_wrapper(self, arguments, expected=0): + result = subprocess.run(['/bin/sh', str(self.project / 'release.sh'), *arguments], + cwd=self.root, env=self.env, capture_output=True, text=True) + self.assertEqual(result.returncode, expected, result.stderr) + self.assertNotIn('inert-test-token-123', result.stdout + result.stderr) + return result + + def set_version(self, version): + manifest = self.project / 'Cargo.toml' + text = manifest.read_text() + old = tomllib.loads(text)['package']['version'] + manifest.write_text(text.replace(f'version = "{old}"', f'version = "{version}"', 1)) + + def test_exact_arguments_token_environment_and_fallback(self): + before = subprocess.check_output(['git', '-C', str(self.project), 'remote', 'get-url', 'origin']) + extra = ['--dry-run', '--message-file', 'notes with spaces; $(not-a-command) *.md'] + self.run_wrapper([self.token.name, *extra]) + record = json.loads(self.capture.read_text()) + self.assertEqual(record['args'], [str(self.project), '--package', 'tiny-wb', '--artifact-format', 'both', *extra]) + self.assertEqual(record['token'], 'inert-test-token-123') + self.assertNotIn(record['token'], '\n'.join(record['args'])) + config = tomllib.loads(record['fallback']) + self.assertEqual(config['repository']['fallbacks'], [{ + 'origin': before.decode().strip(), + 'fallback-url': 'https://proxy.dandaedre.com/gitea/idle-org/tiny-wb'}]) + after = subprocess.check_output(['git', '-C', str(self.project), 'remote', 'get-url', 'origin']) + self.assertEqual(before, after) + + def test_prerelease_and_build_metadata(self): + for version, prerelease in [('1.2.3', False), ('1.2.3-rc.1', True), + ('1.2.3+build-with-hyphen', False), ('1.2.3-rc.1+build', True)]: + with self.subTest(version=version): + self.set_version(version) + self.run_wrapper([str(self.token), '--dry-run']) + self.assertEqual('--prerelease' in json.loads(self.capture.read_text())['args'], prerelease) + + def test_publisher_exit_status_and_nonterminated_token(self): + self.env['PUBLISHER_EXIT'] = '37' + self.token.write_text('inert-test-token-123') + self.run_wrapper([str(self.token), '--compile-only'], expected=37) + self.assertEqual(json.loads(self.capture.read_text())['token'], 'inert-test-token-123') + + def test_invalid_token_inputs_never_invoke_publisher(self): + self.run_wrapper([], expected=2) + self.run_wrapper([str(self.root / 'missing')], expected=2) + self.run_wrapper([str(self.root)], expected=2) + for contents in ('', '\nsecond-line-is-not-a-token\n'): + self.token.write_text(contents) + self.run_wrapper([str(self.token)], expected=2) + self.assertFalse(self.capture.exists()) + + @unittest.skipIf(os.geteuid() == 0, 'root bypasses ordinary readability checks') + def test_unreadable_token(self): + self.token.chmod(0) + try: + self.run_wrapper([str(self.token)], expected=2) + self.assertFalse(self.capture.exists()) + finally: + self.token.chmod(0o600) + + def test_missing_publisher_and_unresolved_version(self): + self.fake.unlink() + self.run_wrapper([str(self.token)], expected=2) + self.fake.write_text('#!/bin/sh\nexit 99\n') + self.fake.chmod(0o755) + for manifest in ('[package]\nname="tiny-wb"\n', + '[package]\nversion.workspace=true\n[dependencies.example]\nversion="1.2.3"\n', + '[package]\nversion="not-semver"\n'): + (self.project / 'Cargo.toml').write_text(manifest) + self.run_wrapper([str(self.token)], expected=2) + (self.project / 'Cargo.toml').unlink() + self.run_wrapper([str(self.token)], expected=2) + + def test_xtrace_does_not_expose_token(self): + result = subprocess.run(['/bin/sh', '-x', str(self.project / 'release.sh'), str(self.token), '--dry-run'], + cwd=self.root, env=self.env, capture_output=True, text=True) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertNotIn('inert-test-token-123', result.stdout + result.stderr) + + def test_metadata_agrees_with_tag_and_archive_policy(self): + manifest = tomllib.loads((REPO / 'Cargo.toml').read_text())['package'] + config = tomllib.loads((REPO / 'rust-release.toml').read_text()) + self.assertEqual(manifest['name'], 'tiny-wb') + self.assertEqual(config['release']['tag-prefix'], '') + self.assertEqual(config['build']['profile'], 'release') + self.assertTrue(config['build']['locked']) + self.assertEqual(config['build']['targets'], ['x86_64-unknown-linux-gnu', 'x86_64-pc-windows-gnu']) + self.assertEqual(manifest['metadata']['binstall'], { + 'pkg-url': '{ repo }/releases/download/{ version }/{ name }-{ target }-v{ version }.tgz', + 'pkg-fmt': 'tgz', + 'bin-dir': '{ name }-{ target }-v{ version }/{ bin }{ binary-ext }'}) + + +if __name__ == '__main__': + unittest.main()