Skip to content

Commit d91cdd6

Browse files
committed
docs: Provide pointers for MSRV
In today's cargo team meeting, we discussed the Pre-RFC for MSRV-aware resolver. In that discussion, the question of recommending a policy came up. While we didn't feel the ecosystem has coalesced enough to set one (and we hope MSRV-aware resolver will avoid the need), it became clear that some we can provide some basic help to the user, including - Raising awareness of tools to find the actual MSRV - The policy that they should verify it with examples on how to do so While this recommends some specific third-party tools, I'm not aware of other tools within this for us to worry about at this time for us to create any guidelines on which we should include.
1 parent 30efe86 commit d91cdd6

File tree

2 files changed

+28
-0
lines changed

2 files changed

+28
-0
lines changed

src/doc/src/guide/continuous-integration.md

+24
Original file line numberDiff line numberDiff line change
@@ -156,6 +156,30 @@ jobs:
156156
For projects with higher risks of per-platform or per-Rust version failures,
157157
more combinations may want to be tested.
158158

159+
## Verifying `rust-version`
160+
161+
When publishing packages that specify [`rust-version`](../reference/manifest.md#the-rust-version-field),
162+
it is important to verify the correctness of that field.
163+
164+
Some third-party tools that can help with this include:
165+
- [`cargo-msrv`](https://crates.io/crates/cargo-msrv)
166+
- [`cargo-hack`](https://crates.io/crates/cargo-hack)
167+
168+
An example of one way to do this:
169+
```yaml
170+
jobs:
171+
msrv:
172+
runs-on: ubuntu-latest
173+
steps:
174+
- uses: actions/checkout@v4
175+
- uses: taiki-e/install-action@cargo-hack
176+
- run: cargo hack check --rust-version --workspace --all-targets --ignore-private
177+
```
178+
This tries to balance thoroughness with turnaround time:
179+
- A single platform is used as most projects are platform-agnostic, trusting platform-specific dependencies to verify their behavior.
180+
- `cargo check` is used as most issues contributors will run into are API availability and not behavior.
181+
- Unpublished packages are skipped as this assumes only consumers of the verified project, through a registry, will care about `rust-version`.
182+
159183
[`cargo add`]: ../commands/cargo-add.md
160184
[`cargo install`]: ../commands/cargo-install.md
161185
[Dependabot]: https://docs.github.com/en/code-security/dependabot/working-with-dependabot

src/doc/src/reference/manifest.md

+4
Original file line numberDiff line numberDiff line change
@@ -185,6 +185,10 @@ The `rust-version` may be ignored using the `--ignore-rust-version` option.
185185
Setting the `rust-version` key in `[package]` will affect all targets/crates in
186186
the package, including test suites, benchmarks, binaries, examples, etc.
187187

188+
To find the minimum `rust-version` compatible with your project, you can use third-party tools like [`cargo-msrv`](https://crates.io/crates/cargo-msrv).
189+
190+
When used on packages that get published, we recommend [Verifying `rust-version`](../guide/continuous-integration.md#verifying-rust-version).
191+
188192
### The `description` field
189193

190194
The description is a short blurb about the package. [crates.io] will display

0 commit comments

Comments
 (0)