Skip to content

Latest commit

 

History

History
111 lines (86 loc) · 5.37 KB

RELEASE.md

File metadata and controls

111 lines (86 loc) · 5.37 KB

Release Process

Publishing is handled by .github/workflows/ci.yml: pushing a tag X.Y.Z (or a milestone X.Y.Z-Mn or release candidate X.Y.Z-RCn) to a commit on main publishes that version to crates.io, Maven Central, NuGet, and the docs site, and opens a draft GitHub release. This file covers only the human steps around that trigger.

1. Prepare a prepare X.Y.Z PR against main

Bump the version and refresh Cargo.lock:

./bump-version.sh X.Y.Z

The script rewrites the version in every file that hard-codes it (Cargo manifests, the poms, the .csproj examples, the C CMakeLists.txt, and guide/sitedata.json), updates Cargo.lock, and verifies nothing was missed. The file list lives in the script — keep it there, not duplicated here.

Then update CHANGELOG.md (see conventions below). If any dependency versions changed, refresh allowed.json so the packaging license check passes, and verify any dependency/security claims in the changelog against the actual Cargo.lock versions.

The merge queue builds the bindings and their packages and runs the packaging license check, so a broken cross-compile or license check stops the PR before it reaches main. To see them before queueing, run gh workflow run ci.yml --ref <prepare-branch>.

2. Tag on main and push

CI only publishes from tags, and by convention tags live on main. Tag the commit the prepare PR's merge produced, by its SHA, since main may have moved since:

git checkout main && git pull
SHA=$(gh pr view <prepare PR number> --json mergeCommit --jq .mergeCommit.oid)
git tag X.Y.Z "$SHA" && git push origin X.Y.Z

The tag name must exactly match the version in Cargo.toml: CI derives the published version from it. Bare semver, no v prefix.

crates.io publishing is irreversible — a version can never be re-published. Confirm the version before pushing. (-Mn and -RCn publish as pre-releases, which cargo won't select by default.)

3. Approve the release jobs

Once the tag's checks pass, the publishing jobs wait for a maintainer to approve their environments (crates-io, nuget and release) on the run's page. First release-check confirms the tag matches the crate version; then crates.io, NuGet, Maven Central and the docs publish, and release-maven waits until the version is published on Maven Central. Last, create-github-release asks for approval again, attests the release files and creates the draft release with them.

4. After CI completes

Review and publish the draft GitHub release CI created (-Mn and -RCn drafts are already marked as pre-releases). The publishers are idempotent, so re-running the tag's workflow safely retries any that failed. If only create-github-release failed, the packages are out without attestations until it's re-run, so re-run it from the run's page; it asks for approval again and replaces its own draft.

Dependencies

Dependency security is handled continuously, not at release time: .github/workflows/security-audit.yml runs cargo audit and osv-scanner daily, on every PR, and on every main push that touches Cargo.toml/Cargo.lock, and fails on advisories. Security patches land as their own PRs as advisories appear — they are not batched onto releases.

The release's dependency responsibilities are therefore narrow:

  • Gate, don't churn: the security audit must be green on the prepare PR (it runs on every PR). Don't tag if it's red. The prebuilt bindings (C/.NET/Java) freeze whatever is in Cargo.lock at tag time, so a clean audit at the tag is what protects binding consumers — pure-Rust crate consumers re-resolve on their own.
  • Freshen early, once per cycle: do the routine "update dependencies" pass at the first RC/milestone of a new minor version, not at each RC and not at the final release. Late-cycle dependency churn undermines the stabilization the RC process exists to provide. Subsequent RCs and the final release take security patches only (targeted cargo update -p <crate>).

Toolchain

rust-toolchain.toml pins the Rust toolchain CI builds, tests and releases with. Raise it to the current stable with the dependency pass at the first RC or milestone of each minor version, and confirm the no-panic and semver jobs still pass (raise the pinned cargo-semver-checks with it if rustdoc's JSON format changed). Raise it out of cycle only for a confirmed miscompilation or a rustc security fix. The msrv job checks the declared rust-version separately.

CI builds cargo-audit, cargo-semver-checks and zizmor from crates.io at the versions its workflows name, which Dependabot doesn't update. Raise them to their latest releases at the same time.

CHANGELOG conventions

  • The upcoming release has one section, headed by its final version (### X.Y.Z ###), from the first milestone through the final release. Milestone and release-candidate tags publish it as it stands; there are no per-pre-release sections to collapse.
  • Markers: :rotating_light: for a vulnerability with an advisory (the first bullet, led by bold "Security advisory:"), then optionally one bold headline bullet for the release's theme, then by type: :bell: behavior or compatibility changes, :shield: hardening, :star: features, :bug: fixes, :wrench: tooling and CI, :book: docs. Each bullet links its PR or issue, except the headline, which summarizes without links.