Before publishing 2.1.0 of a Rust crate, what does cargo-semver-checks compare, how does it pick a baseline, and what can it miss?
answer
- two rustdoc JSON files
- newest normal version not above yours
- the bump comes from version numbers
- exit status 100
basics
~20 scargo-semver-checks compares rustdoc JSON of the current crate against a baseline release, by default the newest non-yanked, non-prerelease version on crates.io not above yours. It fails if 2.1.0 needs a bigger bump; some breaks, like changed field types, still slip through.
solid answer
~40 s`cargo semver-checks` generates rustdoc JSON for the working tree and for a baseline and runs lints over the difference, each lint naming the version bump it requires. By default the baseline is the largest crates.io version that is neither yanked nor a prerelease and not above your manifest's version, so with 2.0.3 yanked it compares against 2.0.2. The release type comes from comparing the two version numbers (override with `--release-type`). Custom registries are not supported, so an internal crate uses `--baseline-rev` (a git tag) or `--baseline-root`. Exit status 0 means no deny-level violations, 100 means it found some, 101 means the check could not run. It does not catch everything: changed field or parameter types, generics and lifetimes, and breaks visible only under some features are listed gaps.
code
toml · 7 lines[package]
name = "quantile-sketch"
version = "2.1.0"
edition = "2024"
[package.metadata.cargo-semver-checks.lints]
function_must_use_added = "warn"go deeper
Recall that cargo publish does not check compatibility and that cargo-semver-checks is the tool people run before releasing.
Explain the mechanics: rustdoc JSON for current and baseline, lints with a required update, and the release type taken from the version numbers.
Configure baselines that work for your registry, interpret exit codes 100 and 101 in CI, and know the classes of break the tool still misses.
Decide where the tool sits in the release gate and who may downgrade a lint, keeping API review for the breaks no lint covers.
## What the tool is **cargo-semver-checks** is a third-party Cargo subcommand (installed with `cargo install cargo-semver-checks --locked`, run as `cargo semver-checks`) that lints a crate's public API for **SemVer violations before you publish**. Cargo itself does not compare APIs: `cargo publish` uploads whatever version number the manifest states. Deciding which Rust changes break callers is a language question; this tool automates catching many of them. It works on **rustdoc JSON**, rustdoc's machine-readable description of a crate's public items: 1. Build rustdoc JSON for the **current** crate (your working tree). 2. Build rustdoc JSON for a **baseline** release. 3. Run its lints, each a query over both API descriptions, such as `function_missing` (a public function disappeared). 4. Compare each finding's **required update** (major or minor) with the release type implied by the version numbers. Because rustdoc JSON is unstable, each cargo-semver-checks release supports the then-current stable and beta Rust; update the tool when you update the toolchain. ## How the baseline is chosen | Flag | Baseline | |---|---| | none | crates.io: the largest version that is not yanked, not a prerelease, and not above the current manifest version | | `--baseline-version X.Y.Z` | that version from the registry | | `--baseline-rev REV` | a git revision, such as the tag of the last release | | `--baseline-root DIR` | a directory containing the baseline source | | `--baseline-rustdoc FILE` | a prepared rustdoc JSON file | For the maintainer of `quantile-sketch` who yanked a broken 2.0.3 and is about to publish 2.1.0, the default baseline is **2.0.2**: the yanked version is skipped. If no normal version exists, the tool falls back to the largest version including yanked and prerelease ones. Two practical limits follow from this: - **Custom registries are not supported** for baseline lookup. A crate published only to a private Cargo registry needs `--baseline-rev v2.0.2` or `--baseline-root`. - The **release type** is derived from the two version numbers (2.0.2 to 2.1.0 is a minor release); `--release-type` overrides it. ## Reading the result The exit status is designed for CI: - `0`: the check completed without deny-level violations; - `100`: it completed and found one or more **deny-level** violations; - `101`: it could not complete, for example a rustdoc or build failure or a connectivity problem. Each lint has a **level** (`deny`, `warn`, `allow`) and a **required update** (`major` or `minor`), configurable per package under `[package.metadata.cargo-semver-checks.lints]` or once for a workspace under `[workspace.metadata.cargo-semver-checks.lints]`. Configuration in the baseline version is ignored; the current manifest decides. ## Features, targets and what it misses By default it checks with **all features except** ones named `unstable`, `nightly`, `bench` or `no_std`, or starting with `_`, `unstable-` or `unstable_`; `--all-features`, `--default-features` and `--only-explicit-features` change that. Target-specific APIs need one run per target triple (`--target`), and `--cfg` options go through `RUSTDOCFLAGS`. The project's own README lists areas where it **currently does not catch** violations: - breaking **type changes**, such as a field's or parameter's type; - breaking changes in **generics or lifetimes**; - breaks that appear only when a **subset of features** is enabled. Its design goal is no false positives, so a report is a strong signal; silence is not proof. A release gate therefore pairs it with review of the public API diff and a changelog, and with the decision on whether a finding means bumping to 3.0.0 or reverting the change. ## Where it sits in a release A release job for 2.1.0 usually runs the checks from cheapest to most final: 1. `cargo semver-checks` against the last good release, failing the job on exit status 100. 2. `cargo package` (or `cargo publish --dry-run`) to prove the tarball builds. 3. `cargo publish`, only after both pass, because the upload cannot be undone. Running step 1 on every pull request, not only at release time, moves the conversation about a breaking change to the review where it was introduced.
- How do you semver-check a crate that lives only in a private Cargo registry?Point the tool at a baseline it can build itself. `cargo semver-checks --baseline-rev v2.0.2` checks out that git revision, and `--baseline-root` takes a directory of source. Registry lookup works only against crates.io today.
- The tool reports a deny-level violation on the way to 2.1.0. What are the honest options?Either the change really breaks callers, and you revert it or release 3.0.0, or the lint is too strict for your policy, and you lower its level or required update in `[package.metadata.cargo-semver-checks.lints]`. Silencing it without that decision just ships the break.
- Cargo refuses to publish a minor release that breaks the API
- A clean cargo-semver-checks run proves the release is compatible
- It compares against the newest version even if that one is yanked
- It looks up baselines in any configured Cargo registry
- Exit status 101 means a SemVer violation was found