! Disclaimer !: This repository is no longer maintained and our advice is to use https://crates.io/crates/cargo-semver-checks instead.

Logo is provided by Morgane Gaillard (@Arlune) under the MPL license.

cargo-breaking compares a crate's public API between two different branches, shows what changed, and suggests the next version according to semver.

Suppose you're building a crate that, for any reason, deals with users. The crate version is 2.4.3. You remove the User::from_str method, add a new public field to User, implement Debug for it and add the User::from_path function.

When invoked, the following text should be printed:

$ cargo breaking
- user::User::from_str
≠ user::User
+ user::User::from_path
+ user::User: Debug
Next version is: 3.0.0

against, an arg to specify the github ref (a tag, a branch name or a commit) against which we can compare our current crate version.

• use:

cargo breaking -a branch_name

• default: "main"

cargo-breaking aims to detect most breaking changes, but deliberately chooses to ignore the most subtle ones. This includes, but is not limited to:

• when the size of a type changes (playground example),
• when a public trait is implemented for a type (see assert_not_impl_any).

By default, cargo-breaking compares the public API of the crate against what is exposed in the main branch. This can be changed with the --against (abbreviated by -a) parameter. The value can be a branch name, a tag name, or a commit SHA-1.

It currently detects the following:

• functions,
• struct fields and generic parameters,
• enum variants, fields and generic parameters,
• methods when the implemented type is simple enough.

As we compare parts of the crate AST, it reports a lot of false positives:

• renaming an argument is reported as a breaking change,
• renaming a generic type is reported as a breaking change,
• adding a generic type with a default value is a breaking change,
• depending on the situation, adding a trailing comma may be a breaking change.

A book is maintained to help understanding how the crate works, and what are its inner parts and their behaviour.

It can be found here : book