From d4bdbc4d414b429d260aad16856bcf084dc77f67 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Thu, 3 Oct 2024 09:03:53 -0500
Subject: [PATCH] docs(ref): Document MSRV-aware resolver

---
 src/doc/src/reference/config.md   | 25 +++++++++++++++++++++++++
 src/doc/src/reference/unstable.md | 26 +-------------------------
 2 files changed, 26 insertions(+), 25 deletions(-)

diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md
index be8bbd24e660..657adbe4557d 100644
--- a/src/doc/src/reference/config.md
+++ b/src/doc/src/reference/config.md
@@ -143,6 +143,9 @@ rpath = false            # Sets the rpath linking option.
 [profile.<name>.package.<name>]  # Override profile for a package.
 # Same keys for a normal profile (minus `panic`, `lto`, and `rpath`).
 
+[resolver]
+incompatible-rust-versions = "allow"  # Specifies how resolver reacts to these
+
 [registries.<name>]  # registries other than crates.io
 index = "…"          # URL of the registry index
 token = "…"          # authentication token for the registry
@@ -972,6 +975,28 @@ See [rpath](profiles.md#rpath).
 
 See [strip](profiles.md#strip).
 
+## `[resolver]`
+
+The `[resolver]` table overrides [dependency resolution behavior](resolver.md) for local development (e.g. excludes `cargo install`).
+
+#### `resolver.incompatible-rust-versions`
+* Type: string
+* Default: `"allow"`
+* Environment: `CARGO_RESOLVER_INCOMPATIBLE_RUST_VERSIONS`
+
+When resolving which version of a dependency to use, select how versions with incompatible `package.rust-version`s are treated.
+Values include:
+- `allow`: treat `rust-version`-incompatible versions like any other version
+- `fallback`: only consider `rust-version`-incompatible versions if no other version matched
+
+Can be overridden with
+- `--ignore-rust-version` CLI option
+- Setting the dependency's version requirement higher than any version with a compatible `rust-version`
+- Specifying the version to `cargo update` with `--precise`
+
+> **MSRV:**
+> - `allow` is supported on any version
+> - `fallback` is respected as of 1.83
 
 ### `[registries]`
 
diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md
index 1b92ffbaf67f..8de2734af2af 100644
--- a/src/doc/src/reference/unstable.md
+++ b/src/doc/src/reference/unstable.md
@@ -343,31 +343,7 @@ This was stabilized in 1.79 in [#13608](https://github.com/rust-lang/cargo/pull/
 
 ### MSRV-aware resolver
 
-`-Zmsrv-policy` allows access to an MSRV-aware resolver which can be enabled with:
-- `resolver.incompatible-rust-versions` config field
-- `workspace.resolver = "3"` / `package.resolver = "3"`
-- `package.edition = "2024"` (only in workspace root)
-
-The resolver will prefer dependencies with a `package.rust-version` that is the same or older than your project's MSRV.
-As the resolver is unable to determine which workspace members will eventually
-depend on a package when it is being selected, we prioritize versions based on
-how many workspace member MSRVs they are compatible with.
-If there is no MSRV set then your toolchain version will be used, allowing it to pick up the toolchain version from pinned in rustup (e.g. `rust-toolchain.toml`).
-
-#### `resolver.incompatible-rust-versions`
-* Type: string
-* Default: `"allow"`
-* Environment: `CARGO_RESOLVER_INCOMPATIBLE_RUST_VERSIONS`
-
-When resolving a version for a dependency, select how versions with incompatible `package.rust-version`s are treated.
-Values include:
-- `allow`: treat `rust-version`-incompatible versions like any other version
-- `fallback`: only consider `rust-version`-incompatible versions if no other version matched
-
-Can be overridden with
-- `--ignore-rust-version` CLI option
-- Setting the dependency's version requirement higher than any version with a compatible `rust-version`
-- Specifying the version to `cargo update` with `--precise`
+This was stabilized in 1.83 in #.
 
 ### Convert `incompatible_toolchain` error into a lint