90 lines
4.0 KiB
Markdown
90 lines
4.0 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
cargo binstall --git https://proxy.dandaedre.com/gitea/idle-org/rust_realease \
|
|
rust_realease
|
|
rust_realease --help
|
|
```
|
|
|
|
See the [upstream repository](https://proxy.dandaedre.com/gitea/idle-org/rust_realease) 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:
|
|
|
|
```sh
|
|
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](development.md#quality-gates), 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:
|
|
|
|
```sh
|
|
./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:
|
|
|
|
```sh
|
|
./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:
|
|
|
|
```sh
|
|
./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.
|