Compare commits
1 Commits
| Author | SHA1 | Date |
|---|---|---|
|
|
82ba741790 |
209
README.md
209
README.md
|
|
@ -1,3 +1,210 @@
|
|||
# target_test_project
|
||||
|
||||
Target project for the rust_release project
|
||||
`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<version>` 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<version>` 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 <target-triple>` 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`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue