From 3cc9586b37d28795c75fbefb6955678d01ab5d1b Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 28 Nov 2023 11:42:45 -0600 Subject: [PATCH] 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. --- src/doc/src/guide/continuous-integration.md | 24 +++++++++++++++++++++ src/doc/src/reference/manifest.md | 4 ++++ 2 files changed, 28 insertions(+) diff --git a/src/doc/src/guide/continuous-integration.md b/src/doc/src/guide/continuous-integration.md index 0c3cec8892c9..282ca1ab8de8 100644 --- a/src/doc/src/guide/continuous-integration.md +++ b/src/doc/src/guide/continuous-integration.md @@ -156,6 +156,30 @@ jobs: For projects with higher risks of per-platform or per-Rust version failures, more combinations may want to be tested. +## Verifying `rust-version` + +When publishing packages that specify [`rust-version`](../reference/manifest.md#the-rust-version-field), +it is important to verify the correctness of that field. + +Some third-party tools that can help with this include: +- [`cargo-msrv`](https://crates.io/crates/cargo-msrv) +- [`cargo-hack`](https://crates.io/crates/cargo-hack) + +An example of one way to do this, using GitHub Actions: +```yaml +jobs: + msrv: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: taiki-e/install-action@cargo-hack + - run: cargo hack check --rust-version --workspace --all-targets --ignore-private +``` +This tries to balance thoroughness with turnaround time: +- A single platform is used as most projects are platform-agnostic, trusting platform-specific dependencies to verify their behavior. +- `cargo check` is used as most issues contributors will run into are API availability and not behavior. +- Unpublished packages are skipped as this assumes only consumers of the verified project, through a registry, will care about `rust-version`. + [`cargo add`]: ../commands/cargo-add.md [`cargo install`]: ../commands/cargo-install.md [Dependabot]: https://docs.github.com/en/code-security/dependabot/working-with-dependabot diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md index 1f53f8b0f1b0..ca97f951985d 100644 --- a/src/doc/src/reference/manifest.md +++ b/src/doc/src/reference/manifest.md @@ -185,6 +185,10 @@ The `rust-version` may be ignored using the `--ignore-rust-version` option. Setting the `rust-version` key in `[package]` will affect all targets/crates in the package, including test suites, benchmarks, binaries, examples, etc. +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). + +When used on packages that get published, we recommend [verifying `rust-version`](../guide/continuous-integration.md#verifying-rust-version). + ### The `description` field The description is a short blurb about the package. [crates.io] will display