john-slop/docs/releasing.md

3.2 KiB

Release procedure

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

If publishing Rust packages, publish and verify john-slop-core first, john-slop-lsp second, and the root john-slop facade last. All three versions must remain synchronized; path dependencies carry matching registry versions. Before publication, assemble all three crates in Cargo's dependency order with scripts/package-workspace.sh --no-verify. The flag is required until the matching core and LSP versions exist in the registry; after publication, rerun the script without it to verify the registry-form dependency graph.

  1. Ensure CHANGELOG.md, Cargo.toml, Cargo.lock, documentation, and the version badge agree; run every command in docs/development.md. Milestone v0.1.N completion commits use package version 0.1.N; regenerate the badge only after updating the manifest and lockfile.

  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 build the release archive:

    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, binary help, archive contents, and recorded sizes. Sign the archive and checksum if a signing identity is available.

  7. Publish the archive, archive checksum, 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.

Publish with rust_realease

Install rust_realease, then pass the path of a readable Gitea token file to the repository wrapper:

./release.sh /path/to/token.txt --dry-run
./release.sh /path/to/token.txt

The wrapper keeps the token out of command-line arguments, exports it as GITEA_TOKEN only to rust_realease, selects the john-slop workspace package, and publishes cargo-binstall archives alongside raw binary artifacts. The project-local rust-release.toml maps the SSH development origin to the canonical HTTPS proxy for release API and download operations without modifying the Git remote. A hyphenated Cargo version such as 0.1.27-rc.6 automatically marks the Gitea release as a prerelease. Additional arguments are forwarded, so use --dry-run before publication and --replace-assets only after reviewing an existing release collision. The checkout must be clean and its local and remote vX.Y.Z tag must match the package version as required by rust_realease.