Recommend package.rust-version in the Rust version section of reference/semver.md.
#15806
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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".
rustbot
added
A-documenting-cargo-itself
weihanglo
reviewed
Aug 5, 2025
| @@ -2028,6 +2028,8 @@ Mitigation strategies: | |||
| [`#[cfg(accessible(..))]`][cfg-accessible] features which provide an opt-in | |||
| mechanism for new features. These are currently unstable and only available | |||
| in the nightly channel. | |||
| * Use [`package.rust-version`] to declare your package’s compatibility. | |||
There was a problem hiding this comment.
- Instead of
cargo update, should we say "Cargo's dependency resolution"? - MSRV resolver at this moment is best-effort, it will still fall back to incompatible version if nothing found, if we want to be more precise.
epage
reviewed
Aug 5, 2025
Comment on lines
+2031
to
+2032
| * Use [`package.rust-version`] to declare your package’s compatibility. | ||
| This allows `cargo update` to avoid introducing an incompatible update. |
There was a problem hiding this comment.
What do you think of:
Suggested change
| * Use [`package.rust-version`] to declare your package’s compatibility. | |
| This allows `cargo update` to avoid introducing an incompatible update. | |
| * Specify your minimum-supported Rust version by setting [`package.rust-version`], allowing Cargo to [select older versions of your package] when needed rather than erroring. Be sure to consider the [support expectations] when doing so. | |
| [`package.rust-version`]: https://doc.rust-lang.org/cargo/reference/rust-version.html | |
| [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 |
- Re-orders and rewords things so the emphasis is on your package's support, to avoid people setting and forgetting this and it being wrong
- Explicitly calling out support expectations to avoid people setting and forgetting this and it being wrong
- Applies feedback from weihanglo
Also, based on what we've written for the package.rust-version page, I think it would be fine to list this first, rather than last.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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-versionis 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".