john-slop/docs/releasing.md

64 lines
3.2 KiB
Markdown

# 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:
```sh
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`](https://proxy.dandaedre.com/gitea/idle-org/rust_realease),
then pass the path of a readable Gitea token file to the repository wrapper:
```sh
./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.8` 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`.