Cargo Documentation for Semantic Versioning

[BKDaugherty]

Problem

While I totally understand cargo's documentation is not intending to be the definitive Rust ecosystem MSRV documentation

These are only guidelines, and not necessarily hard-and-fast rules that all projects will obey. The Change categories section details how this guide classifies the level and severity of a change. Most of this guide focuses on changes that will cause cargo and rustc to fail to build something that previously worked. Almost every change carries some risk that it will negatively affect the runtime behavior, and for those cases it is usually a judgment call by the project maintainers whether or not it is a SemVer-incompatible change.

I think the community has started to settle on a slightly different approach for the following.

Possibly-breaking: changing the minimum version of Rust required

Introducing the use of new features in a new release of Rust can break projects that are using older versions of Rust. This also includes using new features in a new release of Cargo, and requiring the use of a nightly-only feature in a crate that previously worked on stable.

Some projects choose to allow this in a minor release for various reasons. It is usually relatively easy to update to a newer version of Rust. Rust also has a rapid 6-week release cycle, and some projects will provide compatibility within a window of releases (such as the current stable release plus N previous releases). Just keep in mind that some large projects may not be able to update their Rust toolchain rapidly.

Where it seems like the leading thought is

The API guidelines tentatively suggest that, for libraries, an MSRV increase should
not be considered a semver-breaking change. Specifically, when increasing
MSRV:

Larger conversation here: rust-lang/api-guidelines#231 (comment)

Proposed Solution

I'm not sure that this is quite actionable just yet, but feels good to have it filed as an issue. It feels a bit overwhelming for this document to link to an ongoing discussion, but maybe once that has been resolved / documented this could link to that?

Notes

I apologize if this has already been discussed! I know this is a topic many are sick of discussing. I'm also happy to look at updating the docs myself / suggesting something that others can update. Just wanted to file this before I move onto the next task of the day.

[epage]

I think the community has started to settle on a slightly different approach for the following.

The approach mentioned is still inline with the community; it says it is up to the maintainer. It does make it sound like the default stance is for it to be major (with "Some projects..."). I've adjusted that wording in #12122 but didn't outright call it a "minor" change just out of an exuberance of caution in hopes it makes the PR less controversial so it can more easily move forward.