Prepare for merging into cargo

[epage]

Blockers

• Re-license as Apache/MIT? #84
• Settle on long term name #47
• What should the CLI look like? #86
• Add --explain flag for lints #49
• Add --base-version argument #50
• Add --base-git <repo> argument #51
• Add --base-manifest-path <path> argument  #52
• Allow selecting the packages to check with common --workspace, --package, --exclude flags #53
• Mark the rustdoc flags as perma-unstable, behind a -Z flag #54
• Make default baseline the previous stable version in the registry #55
• Lint level control #58
• Manifest checks #48 so we can verify the CLI is general enough
• Feature parity with cargo-semverver; major blockers here:
  • Represent type information in the Trustfall schema #149
  • Tracking issue: Checking cross-crate items #638
• private/hidden features rust-lang/cargo#10882 (see Generating rustdoc with --all-features exposes APIs in an unstable feature #321 for context)
• stable/unstable/nightly-only features rust-lang/cargo#10881 (see Add the ability to exclude experimental features from consideration #315 for context)
• Tracking issue for RFC 1977: public & private dependencies rust-lang/rust#44663
• stabilized existence of rustdoc JSON (unstable format is okay) — RFC in progress

Nice-to-haves

• Changelog output mode #60
• Report "minimum new version" in output #56
• Added deprecated attribute API lint, minor incompatibility level #57
• New API entry lint, minor incompatibility level #59

Open questions

• Integrated into cargo or separate rustup component like clippy?
• How does the process for making new rustdoc JSON formats work w.r.t. cargo-semver-checks merged into cargo?
  • PRs to rust-lang/rust run submodule test suites, like cargo's. Presumably they would test the merged cargo-semver-checks as well.
  • If a PR to rust-lang/rust emits a new rustdoc JSON format version, cargo-semver-checks would need to be updated to support it.
  • That appears to be a chicken-and-egg problem: the PR won't pass, so no new versions of rustdoc-types will exist, so no new cargo-semver-checks -> cycle.

Things to remove

• Leading _ is hidden (blocked on private/hidden features rust-lang/cargo#10882)
• bench, nostd, no_std, private, unstable, unstable[-_].*, nightly (blocked on private/hidden features rust-lang/cargo#10882, stable/unstable/nightly-only features rust-lang/cargo#10881)
• --default-features, --only-explicit-features

Merge Proposal (example):

Motivation

Drawbacks

Behavior

Alternatives

Prior Art

Future Possibilities

[epage]

While we have #86, the thing we need to keep in mind broadly is "what will it take for us to be comfortable locking down the design for near perfect compatibility?"

There several routes to use in answering that question

• Stablize a subset but have vetted enough other designs to know we didn't pin ourselves down
• Flesh out intended workflows polish them up for use.
• Collect feedback
• Put out a proposal to force people to speak up (people are quick to respond when they think someone is wrong on the internet)
• Have an extended out-of-tree period for collecting input, iterating, etc.

Areas we need to consider

• CLI
• Lint names
• Lint behavior
• How to add lints without breaking compatibility
• What level of lints is sufficient for the initial level people use before we allow them to opt-in to more

It might be good to get feedback from clippy on what their compatibility guarantees are around lints. I expect at minimum, we shouldn't be changing them in a way that significantly impacts how people use them.

[thomaseizinger]

Would it make sense to integrate this directly into cargo check and run it by default?

The "no-false-positive" mindset seems like this would be safe!

Alternatively, it could also be part of cargo test, similar to how rustdoc tests run automatically.