220 lines
9.8 KiB
Markdown
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.
|