feat: add project-local rust_realease wrapper and release policy

This commit is contained in:
Dandaedre 2026-10-04 22:40:49 +02:00
parent 9d917f9fc5
commit 8f9059aeff
8 changed files with 411 additions and 0 deletions

3
.gitignore vendored
View File

@ -21,3 +21,6 @@ config.toml
/coverage/
/target-ci/
# rust_realease artifacts and build cache
/dist/

View File

@ -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"

View File

@ -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

View File

@ -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.

173
docs/releases.md Normal file
View File

@ -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 '<version>^{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/<version>`.
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.

60
release.sh Executable file
View File

@ -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 <gitea-token-file> [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 "$@"

18
rust-release.toml Normal file
View File

@ -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"

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

@ -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()