Add release wrapper task
Dandaedre/agent-tasks/pipeline/head This commit looks good
Details
Dandaedre/agent-tasks/pipeline/head This commit looks good
Details
This commit is contained in:
parent
119173c865
commit
3d83737823
|
|
@ -0,0 +1,219 @@
|
|||
<!-- 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.
|
||||
Loading…
Reference in New Issue