diff --git a/tasks/make-release-script.task.md b/tasks/make-release-script.task.md new file mode 100644 index 0000000..15f05b8 --- /dev/null +++ b/tasks/make-release-script.task.md @@ -0,0 +1,219 @@ + + + +# 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 --package --artifact-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 [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.