cargo-breaking

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

Example

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

Installation

cargo-breaking needs the nightly toolchain to be installed to work correctly, but can be compiled with any toolchain.

$ cargo install cargo-breaking

Goals and non goals

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).

Status

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.