agent-tasks/tasks/make-release-script.task.md

220 lines
9.8 KiB
Markdown

<!-- Purpose: Add a safe project-local wrapper for publishing with rust_realease. -->
<!-- Scope: Inspect release readiness, detect collisions, add the wrapper, and verify it without publishing. -->
# Add a `release.sh` wrapper for `rust_realease`
Apply this task to one Rust repository at a time. Use
[`rust_realease`](https://proxy.dandaedre.com/gitea/idle-org/rust_realease)
as the publisher and
[`john-slop`](https://proxy.dandaedre.com/gitea/idle-org/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:
1. the exact Cargo package and binary target(s) to release, especially when the
repository is a workspace;
2. the authoritative package version, expected tag (normally `vX.Y.Z`), tag
prefix, release profile, target matrix, and desired artifact format;
3. the canonical Gitea owner, repository, HTTPS release URL, and current Git
origin; do not infer these only from the checkout directory name;
4. 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;
5. whether the release is public or private and whether cargo-binstall
verification is supported;
6. the project's authoritative format, lint, test, build, packaging, changelog,
reproducibility, and release commands; and
7. how maintainers supply the Gitea token. Prefer a readable token file passed
to the wrapper and exported only as `GITEA_TOKEN` to 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, and `rust_realease` are on `PATH`, print their versions,
and inspect `rust_realease --help`. Confirm Cross and a usable Docker or
Podman backend when the selected targets require them. Confirm cargo-binstall
when producing or verifying `tgz` artifacts.
- If `rust_realease` is 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.lock` is
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 and `HEAD`, the origin URL,
and local and remote refs for the expected tag. A normal publication requires
a clean checkout, a local tag at `HEAD`, 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_realease` plans to create.
A collision is a stop condition. Do not add or use `--replace-assets` unless
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/sh` and `set -eu`;
- require a readable, regular, nonempty token file as its first argument;
- fail clearly when `rust_realease` is 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_TOKEN` without 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_realease` without lossy re-parsing;
- add `--prerelease` for a hyphenated package version when that matches project
policy;
- use `exec` so 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:
```toml
[[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.
```sh
#!/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_TOKEN` and 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 `--prerelease` and 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 origin` remains 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
1. Run the wrapper tests and the repository's relevant format, lint, test,
build, and packaging checks.
2. 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.
3. When resources permit, run the wrapper with `--compile-only` and inspect
`SHA256SUMS`, archive contents, executables, and cargo-binstall metadata. This
builds local artifacts but must not contact Gitea or publish anything.
4. 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.
5. 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.