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.
Bump the version and refresh Cargo.lock:
./bump-version.sh X.Y.ZThe 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>.
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.ZThe 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.)
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.
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.
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
preparePR (it runs on every PR). Don't tag if it's red. The prebuilt bindings (C/.NET/Java) freeze whatever is inCargo.lockat 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>).
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.
- 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.