Skip to content

Commit 2394ea6

Browse files
authored
Recommend package.rust-version in the Rust version section of reference/semver.md. (#15806)
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".
2 parents 8aedaad + f155d5b commit 2394ea6

File tree

1 file changed

+8
-0
lines changed

1 file changed

+8
-0
lines changed

src/doc/src/reference/semver.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2018,6 +2018,10 @@ previous releases). Just keep in mind that some large projects may not be able
20182018
to update their Rust toolchain rapidly.
20192019

20202020
Mitigation strategies:
2021+
* Document your package’s minimum-supported Rust version by setting
2022+
[`package.rust-version`], allowing Cargo’s dependency resolution to
2023+
attempt to [select older versions of your package] when needed.
2024+
Be sure to consider the [support expectations] when doing so.
20212025
* Use [Cargo features] to make the new features opt-in.
20222026
* Provide a large window of support for older releases.
20232027
* Copy the source of new standard library items if possible so that you
@@ -2029,6 +2033,9 @@ Mitigation strategies:
20292033
mechanism for new features. These are currently unstable and only available
20302034
in the nightly channel.
20312035

2036+
[select older versions of your package]: https://doc.rust-lang.org/cargo/reference/resolver.html#rust-version
2037+
[support expectations]: https://doc.rust-lang.org/cargo/reference/rust-version.html#support-expectations
2038+
20322039
### Possibly-breaking: changing the platform and environment requirements {#env-change-requirements}
20332040

20342041
There is a very wide range of assumptions a library makes about the
@@ -2296,6 +2303,7 @@ document what your commitments are.
22962303

22972304
[`cfg` attribute]: ../../reference/conditional-compilation.md#the-cfg-attribute
22982305
[`no_std`]: ../../reference/names/preludes.html#the-no_std-attribute
2306+
[`package.rust-version`]: https://doc.rust-lang.org/cargo/reference/rust-version.html
22992307
[`pub use`]: ../../reference/items/use-declarations.html
23002308
[Cargo feature]: features.md
23012309
[Cargo features]: features.md

0 commit comments

Comments
 (0)