From f155d5bbac12a90c2389cc1fbb111d4bb70c967f Mon Sep 17 00:00:00 2001 From: Kevin Reid Date: Mon, 4 Aug 2025 18:40:53 -0700 Subject: [PATCH] Recommend `package.rust-version` in `reference/semver.md`. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a recommendation that, to mitigate “possibly breaking” Rust version requirement increases, they should be declared using `package.rust-version`. My main goal in this change is to make it *possible to find* the Rust version section in this page by searching it, but the most appropriate way to fit it into this section seemed to me to be making this recommendation. Declaring (and maintaining) `package.rust-version` is additional work, but it is a much lesser burden on maintainers than other items in the same list such as "Provide a large window of support". Co-authored-by: Ed Page --- src/doc/src/reference/semver.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/doc/src/reference/semver.md b/src/doc/src/reference/semver.md index 391b1941092..9017cdfb73d 100644 --- a/src/doc/src/reference/semver.md +++ b/src/doc/src/reference/semver.md @@ -2018,6 +2018,10 @@ previous releases). Just keep in mind that some large projects may not be able to update their Rust toolchain rapidly. Mitigation strategies: +* Document your package’s minimum-supported Rust version by setting + [`package.rust-version`], allowing Cargo’s dependency resolution to + attempt to [select older versions of your package] when needed. + Be sure to consider the [support expectations] when doing so. * Use [Cargo features] to make the new features opt-in. * Provide a large window of support for older releases. * Copy the source of new standard library items if possible so that you @@ -2029,6 +2033,9 @@ Mitigation strategies: mechanism for new features. These are currently unstable and only available in the nightly channel. +[select older versions of your package]: https://doc.rust-lang.org/cargo/reference/resolver.html#rust-version +[support expectations]: https://doc.rust-lang.org/cargo/reference/rust-version.html#support-expectations + ### Possibly-breaking: changing the platform and environment requirements {#env-change-requirements} There is a very wide range of assumptions a library makes about the @@ -2296,6 +2303,7 @@ document what your commitments are. [`cfg` attribute]: ../../reference/conditional-compilation.md#the-cfg-attribute [`no_std`]: ../../reference/names/preludes.html#the-no_std-attribute +[`package.rust-version`]: https://doc.rust-lang.org/cargo/reference/rust-version.html [`pub use`]: ../../reference/items/use-declarations.html [Cargo feature]: features.md [Cargo features]: features.md