Scan your Rust crate for semver violations.
Scan your Rust crate for semver violations.
Lint your crate API changes for semver violations.
# If you already use `cargo-binstall` for faster tool installations:
$ cargo binstall cargo-semver-checks
# Otherwise:
$ cargo install cargo-semver-checks --locked
# Lint a new release for SemVer breakage before `cargo publish`:
$ cargo semver-checksOr use as a GitHub Action (used in .github/workflows/ci.yml in this repo):
- name: Check semver
uses: obi1kenobi/cargo-semver-checks-action@v2Each failing check references specific items in the Cargo SemVer reference or other reference pages, as appropriate. It also includes the item name and file location that are the cause of the problem, as well as a link to the implementation of that query in the current version of the tool.
cargo-semver-checks support?cargo-semver-checks with nightly Rust?cargo-semver-checks enable in the tested crates?--cfg conditional compilation. Can cargo-semver-checks scan it?cargo-semver-checks for multiple target triples?cargo-semver-checks have false positives?cargo-semver-checks catch every semver violation?cargo-semver-checks similar to and different from other tools?cargo-semver-check and cargo-semver-checks?cargo-semver-checks support?cargo-semver-checks uses the rustdoc tool to analyze the crate's API.
Rustdoc's JSON output format isn't stable, and can have breaking changes in new Rust versions.
When each cargo-semver-checks version is released, it will at minimum include support
for the then-current stable and beta Rust versions. It may, but is not guaranteed to,
additionally support some nightly Rust versions.
The GitHub Action by default uses
the most recent versions of both cargo-semver-checks and stable Rust,
so it should be unaffected. Users using cargo-semver-checks in other ways
are encouraged to update cargo-semver-checks when updating Rust versions
to ensure continued compatibility.
cargo-semver-checks with nightly Rust?Support for nightly Rust versions is on a best-effort basis.
It will work often, but not always. If you must use nightly,
it's strongly recommended to pin to a specific nightly version to avoid broken workflows.
cargo-semver-checks relies on the rustdoc JSON format, which is unstable and changes often.
After a new rustdoc JSON format version gets shipped in nightly, it usually takes
several days to several weeks for it to be supported in a new cargo-semver-checks,
during which time it is not possible to use cargo-semver-checks with those nightly versions.
It's also possible that support for some nightly versions may be dropped even while older
stable versions are still supported. This usually happens when a rustdoc format gets superseded by
a newer version before becoming part of any stable Rust. In that case, we may drop support for
that format to conserve maintenance bandwidth and speed up compile times.
For example, cargo-semver-checks v0.24
supported rustdoc formats v24, v26, and v27, but did not support the nightly-only v25 format.
If you'd like extended support for older Rust versions,
or an SLA on supporting new nightly releases, we're happy to offer those on a commercial basis.
It could be in the form of a formal support contract,
or something as simple as discussing expectations over email
and setting up a recurring GitHub sponsorship for an agreed-upon amount.
Please reach out at the email in the Cargo.toml and let us know about what projects this is for and what their needs are.
No, it does not have to be published anywhere. You'll just need to use a flag to help
cargo-semver-checks locate the version to use as a baseline for semver-checking.
By default, cargo-semver-checks uses crates.io to look up the previous version of the crate,
which is used as the baseline for semver-checking the current version of the crate.
The following flags can be used to explicitly specify a baseline instead:
--baseline-version <X.Y.Z>
Version from registry to lookup for a baseline
--baseline-rev <REV>
Git revision to lookup for a baseline
--baseline-root <MANIFEST_ROOT>
Directory containing baseline crate source
--baseline-rustdoc <JSON_PATH>
The rustdoc json file to use as a semver baselineCustom registries are not currently supported (#160), so crates published on registries other than crates.io should use one of the other approaches of generating the baseline.
When looking up a git revision with --baseline-rev,
cargo-semver-checks will walk up the current directory until it finds a .git/ directory to resolve the revision and extract the corresponding worktree.
You can use the following environment variables to influence git repository detection:
GIT_DIR: explicitly set the location of the .git/ directory.
If the value is a relative path, it is resolved from the current working directory.
If this is not set,
cargo-semver-checks will search the current working directory and any of its parents for the .git/ directory.GIT_CEILING_DIRECTORIES: a colon (:) separated list of absolute paths which cargo-semver-checks should not search for the .git/ directory.
This can be used to prevent cargo-semver-checks from searching slow network mounted directories.
This environment variable cannot be used to prevent searching the current working directory,
or a directory explicitly set with GIT_DIR.
If this is not set,
cargo-semver-checks will search the current working directory and any of its parents (up to the root directory).GIT_DISCOVERY_ACROSS_FILESYSTEM: enable git repository detection across filesystems.
By default, cargo-semver-checks will not cross filesystem
boundaries when searching for the .git/ directory.
Set this environment variable to true to enable cross-filesystem detection.
This environment variable has no effect when setting GIT_DIR explicitly.Setting the GIT_DIR environment variable allows using cargo-semver-checks with a non-colocated jujutsu repository.
GIT_DIR="$(jj root)/.jj/repo/store/git" cargo semver-checks --package "foo" --baseline-rev "foo/v0.1.0"cargo-semver-checks enable in the tested crates?By default, checking is done on all features except features named unstable, nightly, bench, no_std, or ones with prefix _, unstable-, or unstable_, as such names are commonly used for private or unstable features.
This behavior can be overridden. Checked feature set can be changed to:
--all-features,--default-features,--only-explicit-features.Additionally, features can be enabled one-by-one, using flags --features, --baseline-features and --current-features.
For example, consider crate serde, with the following features (per v1.0.163):
std - the crate's only default feature,alloc, derive, rc - optional features,unstable - a feature that possibly breaks semver.| used flags | selected feature set | explanation |
|---|---|---|
| none | std, alloc, derive, rc |
Feature unstable is excluded by the default heuristic. |
--features unstable |
std, alloc, derive, rc, unstable |
The flag explicitly adds unstable to the heuristic's selections. |
--all-features |
std, alloc, derive, rc, unstable |
All the features are used, disabling the default heuristic. |
--default-features |
std |
The crate has only one default feature. |
--default-features --features derive |
std, derive |
Feature derive is used along with crate's default features. |
--only-explicit-features |
none | No explicit features are passed. |
--only-explicit-features --features unstable |
unstable |
All features can be added explicitly, regardless of their name. |
--cfg conditional compilation. Can cargo-semver-checks scan it?Yes! You can configure the --cfg options that cargo-semver-checks will use
when scanning your crate by setting them in the RUSTDOCFLAGS environment variable.
For example, you can ask cargo-semver-checks to enable the some-option config
by invoking it as:
RUSTDOCFLAGS="--cfg some-optioNo open issues yet, or sync has not completed.