vsg-bridge-ls/doc/releasing.md

3.2 KiB

Release procedure

release.sh is the project-local wrapper for rust_realease. It releases the single Cargo package and binary named vsg-bridge-ls using the release profile and both cargo-binstall .tgz archives and standalone binaries.

The default target matrix is owned by rust_realease:

  • x86_64-unknown-linux-musl;
  • aarch64-unknown-linux-musl; and
  • x86_64-pc-windows-gnu.

Cross and a working Docker or Podman backend are required for those builds. Cross.toml selects the current upstream Cross images because older tagged Windows GNU images lack the import libraries required by current Rust releases. cargo-binstall is required to verify the archives. Install the publisher from its authoritative repository if rust_realease --version is unavailable:

cargo install --git \
  https://proxy.dandaedre.com/gitea/idle-org/rust_realease.git \
  --locked rust_realease

Release identity

The Cargo version is authoritative and produces a v-prefixed tag. For example, version 0.3.3-rc.1 requires tag v0.3.3-rc.1. A hyphenated Cargo version makes the wrapper add --prerelease automatically.

Development uses the SSH origin git@git.dandaedre.com:MadGobblins/vsg-bridge-ls.git. The exact fallback in rust-release.toml directs release creation, downloads, and cargo-binstall to the public HTTPS repository without changing the Git remote.

This repository does not currently maintain a changelog file. Release notes and version selection must therefore be reviewed from the commits since the prior tag before publication.

Token handling

Pass a readable token file as the first wrapper argument. Only its first line is exported as GITEA_TOKEN; the value is never placed in process arguments. Do not commit the token or its path. The usual workspace-local invocation is:

./release.sh ../gitea_token.txt --dry-run

The token needs repository read and release write access. This is a public repository, so generated downloads and cargo-binstall verification can be performed anonymously after upload.

Verification and publication

Run a syntax check and non-mutating publisher inspection first:

sh -n release.sh
./release.sh ../gitea_token.txt --dry-run

The dry run must report the expected package, version, tag, three targets, artifact names, and HTTPS destination. It does not build, tag, push, create a release, or upload files.

A local build and package inspection is also non-publishing:

./release.sh ../gitea_token.txt --compile-only

Inspect the resulting dist/release-* directory, SHA256SUMS, archives, executables, and cargo-binstall metadata. Generated dist/ content is ignored by Git.

Before a live run, require a clean checkout, confirm that the expected signed tag points to HEAD, push the commit and tag, and verify the same tag exists on the remote. Recheck Gitea for an existing release and asset-name collisions. Then publish explicitly:

./release.sh ../gitea_token.txt

The wrapper itself never edits Git metadata, creates or pushes a tag, or publishes without rust_realease. An existing asset is a hard stop. Never pass --replace-assets unless the exact existing release and assets were inspected and replacement was separately approved.