From 82ba7417904306011777725aaea1d041ddfdb902 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Sun, 4 Oct 2026 02:38:46 +0200 Subject: [PATCH] docs: document rust_realease workflow --- README.md | 209 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 208 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 12822aa..bddb1c9 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,210 @@ # target_test_project -Target project for the rust_release project \ No newline at end of file +`target_test_project` is a small Rust binary used as a disposable integration +target for +[`rust_realease`](https://proxy.dandaedre.com/gitea/idle-org/rust_realease). +It exercises repository preparation, Cross compilation, Gitea release uploads, +checksums, and `cargo-binstall` installation without using a production project. + +The program prints its package version and the architecture and operating +system for which it was compiled. + +## Prerequisites + +Install the following before running a complete release: + +- Rust and Cargo; +- Git; +- Docker or Podman, running and available to + [Cross](https://github.com/cross-rs/cross); +- `cross` and `cargo-binstall`; +- a Gitea token with repository read and release write access; +- working Git credentials with code write access when `rust_realease` pushes + the preparation commit and tag. This repository's `origin` uses SSH, so the + push uses the configured SSH key rather than the Gitea token. + +Install the supporting tools and the publisher: + +```bash +cargo install cross --locked +cargo install cargo-binstall --locked +cargo binstall --git https://proxy.dandaedre.com/gitea/idle-org/rust_realease \ + rust_realease +rust_realease --help +``` + +Alternatively, clone `rust_realease` and install the development checkout with +`cargo install --path . --locked`. + +## One-time repository configuration + +The Git remote for this project uses the internal SSH address while Cargo and +Gitea releases use the public proxy. Add the exact mapping below to +`~/.config/rust_realease/config.toml` on Linux. If the file already exists, +merge this entry with its existing settings instead of replacing the file. + +```toml +[[repository.fallbacks]] +origin = "git@git.dandaedre.com:idle-org/target_test_project.git" +fallback-url = "https://proxy.dandaedre.com/gitea/idle-org/target_test_project" +``` + +This allows `rust_realease` to keep using `origin` for Git operations while it +uses the HTTPS proxy for the Gitea API, release downloads, and cargo-binstall +verification. + +## Preview the existing project + +Clone the fixture, enter it, and run a read-only inspection: + +```bash +git clone git@git.dandaedre.com:idle-org/target_test_project.git +cd target_test_project +rust_realease . --dry-run +``` + +The dry run shows the detected package and version, expected tag, targets, +artifact names, required metadata, and release destination. It does not edit +files, build binaries, create tags, or contact the Gitea release API. + +Version `0.1.3` and tag `v0.1.3` have already been published. Always choose a +new version for another end-to-end test; reusing it causes intentional release +asset collision errors. + +## Make a test release + +### 1. Choose and commit a new version + +Start from an up-to-date, clean branch. Change `package.version` in +`Cargo.toml` to a version that has never been released, for example `0.1.4`. +Then update the lockfile, run the local checks, and commit the version change: + +```bash +git pull --ff-only +cargo check +cargo test +git diff -- Cargo.toml Cargo.lock +git add Cargo.toml Cargo.lock +git commit -m "Bump target_test_project to 0.1.4" +``` + +Replace `0.1.4` in this guide with the version you actually selected. The +publisher expects the tag `v` by default. + +### 2. Preview repository preparation + +```bash +rust_realease . --prepare-repo --dry-run +``` + +Preparation checks and, when necessary, repairs the cargo-binstall metadata, +`.gitignore`, `Cross.toml`, and `Cargo.lock`. Review the displayed diff before +continuing. + +### 3. Prepare, tag, and push + +The following command applies the preparation from a clean checkout, commits +only files managed by the publisher when they changed, creates the annotated +version tag, and atomically pushes the branch and tag. It never force-pushes or +moves an existing tag. + +```bash +rust_realease . --prepare-repo \ + --commit-preparation \ + --create-tag \ + --push-preparation +``` + +If you prefer to review and commit every change manually, run +`rust_realease . --prepare-repo`, commit the resulting files, create an +annotated `v` tag, and push both the branch and tag before publishing. + +### 4. Build the release artifacts locally + +```bash +rust_realease . --compile-only +``` + +This runs host `cargo check` and `cargo test`, builds the default target matrix +with Cross, and writes archives plus `SHA256SUMS` under a new +`dist/release-*/` directory. It does not create or modify a Gitea release. + +The default targets are: + +- `x86_64-unknown-linux-musl`; +- `aarch64-unknown-linux-musl`; +- `x86_64-pc-windows-gnu`. + +Use repeatable `--target ` options to override the matrix. Add +`--recompile` to ignore a reusable successful build, or +`--artifact-format both` to produce standalone binaries as well as the default +cargo-binstall `.tgz` archives. + +### 5. Preview publication + +```bash +rust_realease . --dry-run +``` + +Resolve every reported problem before the live run. In particular, the +checkout must be clean, the local tag must point at `HEAD`, and the same tag +must exist on `origin`. + +### 6. Publish and verify the Gitea release + +Read the token without putting it in shell history, then run the publisher: + +```bash +read -r -s -p 'Gitea token: ' GITEA_TOKEN +printf '\n' +export GITEA_TOKEN +rust_realease . --message "target_test_project 0.1.4" +unset GITEA_TOKEN +``` + +Use `--message-file CHANGELOG.md` instead of `--message` for release notes from +a UTF-8 file. The options are mutually exclusive. + +The live command creates or reuses the tagged Gitea release, uploads every +archive and `SHA256SUMS`, downloads the assets again, verifies their checksums +and layouts, and tests isolated cargo-binstall installations. Existing assets +with the same names stop the upload. Use `--replace-assets` only after checking +the existing release and intentionally deciding to replace them. + +### 7. Check installation as a user + +The publisher already performs this check for public releases, but it can also +be repeated manually: + +```bash +cargo binstall --git \ + https://proxy.dandaedre.com/gitea/idle-org/target_test_project \ + target_test_project +target_test_project +``` + +## Useful variations + +Run against a remote checkout and select its release tag explicitly: + +```bash +rust_realease \ + https://proxy.dandaedre.com/gitea/idle-org/target_test_project.git \ + --tag v0.1.4 +``` + +Stop after host validation without Cross compilation or publication: + +```bash +rust_realease . --stop-after verify +``` + +Build raw executables instead of cargo-binstall archives: + +```bash +rust_realease . --artifact-format binary --compile-only +``` + +For the complete option and configuration reference, see the +[`rust_realease` README](https://proxy.dandaedre.com/gitea/idle-org/rust_realease) +and run `rust_realease --help`.