9.8 KiB
Add a release.sh wrapper for rust_realease
Apply this task to one Rust repository at a time. Use
rust_realease
as the publisher and
john-slop as the
reference integration. Read the target repository's local agent instructions,
release documentation, Cargo manifests, Git configuration, and CI before
changing anything. Preserve unrelated work, follow the repository's commit
policy, and do not push a commit or tag, create a release, upload or replace an
asset, or otherwise publish unless the user explicitly requests it.
The executable is intentionally named rust_realease; retain that upstream
spelling in commands, configuration, tests, and documentation.
Establish the release contract
Before creating the wrapper, determine and record:
- the exact Cargo package and binary target(s) to release, especially when the repository is a workspace;
- the authoritative package version, expected tag (normally
vX.Y.Z), tag prefix, release profile, target matrix, and desired artifact format; - the canonical Gitea owner, repository, HTTPS release URL, and current Git origin; do not infer these only from the checkout directory name;
- whether an exact origin-to-HTTPS fallback is needed in
rust-release.toml, as it is when development uses SSH but releases and downloads use the public proxy; - whether the release is public or private and whether cargo-binstall verification is supported;
- the project's authoritative format, lint, test, build, packaging, changelog, reproducibility, and release commands; and
- how maintainers supply the Gitea token. Prefer a readable token file passed
to the wrapper and exported only as
GITEA_TOKENto the publisher.
Do not copy the package name, origin, fallback URL, targets, or version from the example repository. Do not commit a token, token path, generated release artifacts, or other secret material.
Readiness and collision checks
Perform non-mutating checks before implementation:
- Confirm
git, Cargo, andrust_realeaseare onPATH, print their versions, and inspectrust_realease --help. Confirm Cross and a usable Docker or Podman backend when the selected targets require them. Confirm cargo-binstall when producing or verifyingtgzartifacts. - If
rust_realeaseis absent, report the supported installation command. Do not install or upgrade tools without authorization. If a version is pinned by the project, require that exact version. - Confirm the selected Cargo package and binary targets exist,
Cargo.lockis tracked when locked builds are required, the changelog and package version agree, required release metadata is present, and the intended tag can be derived unambiguously. - Inspect
git status --short, the current branch andHEAD, the origin URL, and local and remote refs for the expected tag. A normal publication requires a clean checkout, a local tag atHEAD, and the same tag on the remote. Do not create, move, force-push, or delete a tag as part of these checks. - Run
rust_realease <repository> --package <package> --artifact-format <format> --dry-run, adding only the confirmed project options. Treat every reported issue as a blocker or an explicit follow-up; do not hide failures. - Check Gitea for a release with the expected tag using its release-by-tag API or the repository UI. Distinguish "not found" from authentication, network, and server errors. If it exists, record whether it is a draft or prerelease and list its asset names. Never print the token or an authorization header.
- Compare existing asset names with the names
rust_realeaseplans to create. A collision is a stop condition. Do not add or use--replace-assetsunless the user has inspected the existing release and explicitly approved replacing those exact assets. An existing release without collisions may be reusable, but report it clearly.
A dry run does not build binaries, mutate Git refs, or create a Gitea release. It is necessary but does not replace the explicit existing-release and asset inspection above.
Implement the integration
Add an executable POSIX release.sh at the repository root. It must:
- use
#!/bin/shandset -eu; - require a readable, regular, nonempty token file as its first argument;
- fail clearly when
rust_realeaseis unavailable; - resolve the repository from the script's own location so invocation works from another working directory;
- export the first token-file line as
GITEA_TOKENwithout placing its value on the command line or printing it; - pass the resolved repository, exact package name, chosen artifact format, and
all additional user arguments to
rust_realeasewithout lossy re-parsing; - add
--prereleasefor a hyphenated package version when that matches project policy; - use
execso signals and the publisher's exit status propagate unchanged; and - make no Git, Cargo metadata, remote, tag, or Gitea changes of its own.
Add a project-local rust-release.toml only when needed. For an SSH development
origin and HTTPS release endpoint, use an exact mapping of this form, with
project-specific values:
[[repository.fallbacks]]
origin = "git@gitea.example.org:owner/project.git"
fallback-url = "https://gitea.example.org/owner/project"
The fallback must not rewrite the configured Git remote. Reuse compatible existing release configuration instead of creating a conflicting second source of truth.
Generic wrapper backup
Use the following full template when the upstream example cannot be reached.
Replace PACKAGE_NAME only after the discovery above. Confirm that the first
manifest version is the selected package version; for a virtual workspace or
a non-root member, replace that lookup with a repository-appropriate Cargo
metadata query and test it.
#!/bin/sh
set -eu
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" ]; then
echo "token file is not a readable regular file: $token_file" >&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" >&2
exit 2
fi
GITEA_TOKEN=
IFS= read -r GITEA_TOKEN <"$token_file" || :
if [ -z "$GITEA_TOKEN" ]; then
echo "token file is empty: $token_file" >&2
exit 2
fi
export GITEA_TOKEN
repository_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
manifest_version=$(sed -n 's/^version = "\([^"]*\)"/\1/p' \
"$repository_dir/Cargo.toml" | head -n 1)
if [ -z "$manifest_version" ]; then
echo "could not determine the selected package version" >&2
exit 2
fi
set -- \
"$repository_dir" \
--package PACKAGE_NAME \
--artifact-format both \
"$@"
case "$manifest_version" in
*-*) set -- "$@" --prerelease ;;
esac
exec rust_realease "$@"
Adapt the artifact format only when the project's consumers require something other than both cargo-binstall archives and standalone binaries. Do not embed publication, tag creation, asset replacement, or a token path into the wrapper.
Tests and documentation
Add a small automated wrapper test using a fake rust_realease executable
ahead of the real one on PATH. Without contacting Gitea, verify that:
- the token reaches the fake process through
GITEA_TOKENand never appears in arguments or output; - the repository path, package, artifact format, and forwarded options are exact, including spaces in paths and arguments;
- a prerelease version adds
--prereleaseand a stable version does not; - the wrapper preserves the publisher's nonzero exit status;
- missing arguments, unreadable or empty token files, a missing publisher, and an unresolved package version fail safely; and
- any repository fallback is visible to the publisher while
git remote get-url originremains unchanged.
Run sh -n release.sh and an available POSIX-shell linter. Make the script
executable and confirm its mode is tracked by Git. Update release documentation
with prerequisites, installation, token handling, the dry-run command, the
normal command, package and artifact choices, fallback behavior, prerelease
behavior, existing-release policy, and the fact that --replace-assets needs a
deliberate decision.
Final verification and handoff
- Run the wrapper tests and the repository's relevant format, lint, test, build, and packaging checks.
- Run the completed wrapper with the real token file and
--dry-run; confirm it reports the expected package, version, tag, targets, artifact names, and HTTPS release destination. Redact secrets from captured output. - When resources permit, run the wrapper with
--compile-onlyand inspectSHA256SUMS, archive contents, executables, and cargo-binstall metadata. This builds local artifacts but must not contact Gitea or publish anything. - Repeat the local/remote tag and Gitea release checks immediately before any separately authorized live publication because remote state may have changed since the initial inspection.
- Inspect the final diff for secrets, example identifiers, generated artifacts, unintended metadata changes, and executable mode. Commit only when the repository's instructions require it.
Report the package, version, expected tag, targets, artifact format, tool versions, dry-run result, existing release and asset status, tests run, changed files, and commit ID if one was created. State any unavailable check plainly. Do not claim a release was published unless a separately authorized live run completed and its uploaded downloads were verified.