From ab8d4ff3392b7f3fbd8df6d0c5222d72678ab50f Mon Sep 17 00:00:00 2001
From: rldyourmnd <danil@nddev.it.com>
Date: Wed, 26 Aug 2026 00:33:11 +0500
Subject: [PATCH] docs: say how the pinned toolchain goes wrong quietly

`rust-toolchain.toml` pins the compiler and rustup honours it, but only if the
`cargo` being run is rustup's shim. A `cargo` installed elsewhere and earlier on
`PATH` does not read that file, and if `rustdoc` resolves to a different release
than `cargo` does, the workspace compiles with one compiler while its doctests
run under another:

    error[E0514]: found crate `serde` compiled by an incompatible version of rustc

Nothing is wrong with the code, and the message does not say so. CONTRIBUTING.md
now names the failure, gives the two commands that show it, and says what to do.
---
 CONTRIBUTING.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 15c19b0..2dda944 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -11,6 +11,34 @@ cargo fmt --all --check
 
 CI runs exactly these, on Linux, macOS and Windows.
 
+## The toolchain, and one way it goes wrong quietly
+
+`rust-toolchain.toml` pins the compiler, and rustup honours it — but only if the
+`cargo` you run is rustup's shim. A `cargo` from somewhere else earlier on
+`PATH` does not read that file, so it builds with whatever version it happens to
+be.
+
+That produces a failure worth recognising, because it looks like a defect in the
+code and is not:
+
+```
+error[E0514]: found crate `serde` compiled by an incompatible version of rustc
+```
+
+It happens when `cargo` and `rustdoc` resolve to different releases — a
+distribution or a package manager can install one and not the other. Check with:
+
+```bash
+command -v cargo rustc rustdoc
+cargo --version && rustdoc --version
+```
+
+If they disagree, put rustup's shims first for the shell you build in:
+
+```bash
+export PATH="$HOME/.cargo/bin:$PATH"
+```
+
 ## What the review looks for
 
 - **A new guard is observed failing first.** A test that has never failed on the