Auto merge of #13056 - epage:msrv, r=weihanglo

docs: Provide pointers for MSRV

### What does this PR try to resolve?

In today's cargo team meeting, we discussed the Pre-RFC for MSRV-aware resolver for #9930.
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

### How should we test and review this PR?

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.

Explanations are given for the example CI job to discourage cargo culting and instead give people the information they need in making decisions relevant to their project.

### Additional information

I'd love to provide information to help users create their own MSRV policy but only if there was an automated way of collecting and reporting some of the data, like crates.io providing a dashboard of MSRVs set or rust-versions inferred from user-agents.

Without that, I felt it not worth getting into other policy discussions like reactive vs proactive updating of MSRV, automated MSRV updates, etc.  These can always be added later.

This also helps towards #5656.

Author: bors

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

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 the `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