john-slop/docs/releasing.md

1.6 KiB

Release procedure

Releases are built from a clean, reviewed Linux checkout with the exact Rust toolchain recorded in BUILD-INFO.

  1. Ensure CHANGELOG.md, Cargo.toml, Cargo.lock, documentation, and the version badge agree; run every command in docs/development.md.

  2. Run normal Criterion sampling and the fuzz targets appropriate to changes.

  3. Commit the release preparation and create signed or annotated tag vX.Y.Z.

  4. Check out that tag and install the pinned SBOM tool:

    cargo install cargo-cyclonedx --locked --version 0.5.9
    scripts/package-release.sh X.Y.Z
    
  5. Run the packaging command a second time in a fresh checkout with the same Rust version and compare the archive SHA-256 digest.

  6. Inspect BUILD-INFO, SHA256SUMS, the CycloneDX 1.5 JSON SBOM, binary help, archive contents, and recorded sizes. Sign the archive and checksum if a signing identity is available.

  7. Publish the archive, archive checksum, SBOM, changelog excerpt, and signature together. Never publish an untagged or dirty build as a release.

SOURCE_DATE_EPOCH comes from the tagged commit. The release profile uses thin LTO, one codegen unit, abort-on-panic, and symbol stripping; GNU tar normalizes entry order, timestamps, ownership, and gzip metadata. Reproducibility still depends on the same target, Rust toolchain, linker, and system libraries, all of which must be recorded or controlled by the release environment.

The packaging smoke test produced byte-identical archives in two consecutive runs on the Milestone 7 development host and validated both archive and internal checksums plus the CycloneDX 1.5 schema markers.