Skip to content
This repository has been archived by the owner on Nov 30, 2022. It is now read-only.

Latest commit

 

History

History
87 lines (58 loc) · 2.77 KB

README.md

File metadata and controls

87 lines (58 loc) · 2.77 KB
Raw

cargo-breaking

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

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

Args

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"

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:

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.

Contribution

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