Skip to content

X0028 semver-checks-breaking

Rule: A stable crate changes its public API only with the version bump the change needs.

Code X0028 (stable, never reused)
Id semver-checks-breaking
Category semver
Source cargo-semver-checks (run as an executable)
Fix by hand
Needs cargo-semver-checks installed

Level per tier

Tier Level Reason
small off
small-workspace off
medium off
big deny a crate the map marks stable changes its API only with the version bump it needs
ai off
embedded off
ui off
egui off
units-strict off
units-paranoid off

Parameters

Name Type Default Meaning
packages list of strings [] the crates to check; empty: the crate map's stable crates, without a map the published ones
baseline-rev string "" a git revision to compare with instead of the latest release on crates.io
baseline-root string "" a directory with the baseline's sources, relative to the project root, instead of crates.io

Why

A crate others build on promises that a minor or patch release does not break them. cargo-semver-checks compares the public API with the last release (or a git revision) and names every change the version bump does not cover: a removed function, a new field in a struct built with a literal, a trait that lost an implementation.

Which crates are stable is written once: stable = true in the crate map, or, without a map, every published crate.

[map.crates]
wire_core = { layer = "core", stable = true }

How to fix

Bump the version as the finding says (a new major version for a breaking change), or keep the old API: re-export a moved item, add #[non_exhaustive] before the first release.

Configure

[lints.semver-checks-breaking]
level = "deny"
packages = []
baseline-rev = ""
baseline-root = ""
reason = "why this project wants it at this level"

Allow one finding in the code with // spirit-level: allow(semver-checks-breaking) <reason> (waivers); the code works there too, as in [lints.X0028].