rping/docs/releasing.md

4.0 KiB

Release procedure

This page documents release preparation and publication for the rping package and its rping binary. The package version in Cargo.toml is authoritative; version X.Y.Z uses tag vX.Y.Z.

Release contract

  • Canonical repository: Archive/rping
  • Public release URL: https://proxy.dandaedre.com/gitea/Archive/rping/releases
  • Package and binary: rping
  • Profile: release
  • Artifact format: cargo-binstall .tgz archives and standalone binaries (both)
  • Targets: x86_64-unknown-linux-musl, aarch64-unknown-linux-musl, and x86_64-pc-windows-gnu
  • Tag prefix: v

The repository is public and contains cargo-binstall metadata. The local wrapper uses the default target matrix reported by rust_realease; pass explicit --target options only as a deliberate release-policy change.

Prerequisites

Install and verify:

  • rust_realease
  • Cross
  • a working Docker or Podman backend
  • cargo-binstall
  • Git and the Rust toolchain pinned by rust-toolchain.toml

The publisher executable intentionally uses the upstream spelling rust_realease. Its preferred installation method is:

cargo binstall --git https://proxy.dandaedre.com/gitea/idle-org/rust_realease \
  rust_realease
rust_realease --help

See the upstream repository for source-installation alternatives.

Prepare a token file outside the repository. Its first line must contain a Gitea token able to inspect and create releases for Archive/rping. Restrict the file to the maintainer account, for example:

chmod 600 /path/to/gitea-token.txt

Never commit the token or pass its value on the command line. release.sh reads the first line and exports it only as GITEA_TOKEN to rust_realease.

Prepare and verify

  1. Update CHANGELOG.md, Cargo.toml, and Cargo.lock so the changelog and package version agree.
  2. Run every command in Development and CI, including coverage.
  3. Verify the release wrapper tests with cargo test --locked --test release_wrapper.
  4. Commit the reviewed preparation.
  5. Create an annotated or signed vX.Y.Z tag at that commit and push the commit and tag through the normal reviewed Git workflow.
  6. Confirm the checkout is clean and that the local and remote tags resolve to HEAD.
  7. Check the Gitea release-by-tag API or repository UI for an existing release and list all existing asset names.

The wrapper never creates, moves, pushes, or deletes Git tags. It also does not edit Cargo metadata, Git remotes, or releases before invoking the publisher.

Dry run and packaging

Always start with a dry run:

./release.sh /path/to/gitea-token.txt --dry-run

Confirm the package, version, tag, three targets, artifact names, and proxy release destination. Treat every reported issue as a blocker.

When local resources permit, build and inspect the complete package set without contacting Gitea:

./release.sh /path/to/gitea-token.txt --compile-only

Inspect SHA256SUMS, archive contents, executable names and modes, and cargo-binstall metadata. Repeat the build in a clean checkout with the same toolchain and compare checksums when reproducibility is required.

Publish

Immediately before publishing, repeat the tag, release, and asset collision checks. Then run:

./release.sh /path/to/gitea-token.txt

A hyphenated package version such as 0.2.0-rc.1 automatically adds --prerelease; a stable version does not. Additional arguments are forwarded exactly to rust_realease.

An existing release is not permission to overwrite assets. Stop on any asset-name collision. Use --replace-assets only after inspecting that exact release and explicitly deciding that the named assets should be replaced.

Repository fallback

Development uses the unchanged SSH origin git@git.dandaedre.com:Archive/rping.git. rust-release.toml maps only that exact origin to https://proxy.dandaedre.com/gitea/Archive/rping for release API and download operations. The fallback does not rewrite the Git remote.