-
-
Notifications
You must be signed in to change notification settings - Fork 103
Description
Steps to reproduce the bug with the above code
It is possible to use #[doc(hidden)]
to implement seemingly-breaking changes without actually breaking semver compatibility.
Since cargo-semver-checks
only uses the json rustdoc output to form its analysis, the claim that cargo-semver-checks
has no false positives should probably have this shortcoming noted in the readme.
e.g. these two versions of the same code below are technically semver compatible:
pub struct Foo {}
pub struct Bar {}
#[doc(hidden)]
pub struct Foo {}
pub struct Bar {}
as merely hiding a type (or as is more often, a method) from the documentation doesn't break the semver contract.
or, for a more interesting case, the following:
pub struct Fo {}
pub struct Foo {}
// The previous release included a typo in the type name so the following is kept for backwards-compatibility:
#[doc(hidden)]
pub type Fo = Foo;
There is a lot more dark magic that can done that would break docs but preserve backwards compatibility. Relying solely on the docs is a great and efficient way of implementing straightforward semver breakage cases, but I don't think it's fair to claim that any tool using this approach has no false positives.
Actual Behaviour
A breaking change is reported.
Expected Behaviour
No breaking change should be reported (though I realize this is fundamentally not possible for this crate as it is written).
As such, the "no false positives" claim should be removed or at least the caveats thoroughly mentioned.
Additional Context
No response
Debug Output
No response