Skip to content

Commit

Permalink
docs: Provide pointers for MSRV
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
epage committed Nov 28, 2023
1 parent 2d1c64b commit 3cc9586
Show file tree
Hide file tree
Showing 2 changed files with 28 additions and 0 deletions.
24 changes: 24 additions & 0 deletions src/doc/src/guide/continuous-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions src/doc/src/reference/manifest.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 3cc9586

Please sign in to comment.