Pin the cargo-readme version CI installs

.github/workflows/build.yml

@@ -82,7 +82,11 @@ jobs:
           ${{ runner.os }}-build-
           ${{ runner.os }}-
 
-    - run: cargo install cargo-readme
+    # Pinned: `make check/readme` byte-compares the generated README, so an
+    # unpinned install fails the build whenever cargo-readme changes its output,
+    # with nothing in the diff to explain it. Bump this together with a
+    # regenerated README.md. See specs/design/0049-pin-cargo-readme.md.
+    - run: cargo install cargo-readme --version 3.4.0 --locked
 
     - run: make ci
       name: 'Running `make ci`'

AGENTS.md

@@ -272,11 +272,17 @@ This runs: `make check` (`check/fmt` + `check/readme` + `check/clippy` + `check/
 ## README Sync
 `README.md` is generated from `src/lib.rs` doc comments by `cargo-readme` — **never edit `README.md` directly**. Any change to the README (wording, tables, examples) must be made in the `src/lib.rs` doc comments and then regenerated; a hand-edit to `README.md` is overwritten on the next regeneration and will fail `make check/readme`.
 ```bash
-cargo install cargo-readme   # one-time, if not already installed
+cargo install cargo-readme --version 3.4.0 --locked   # one-time; pin matches CI
 make docs          # regenerate README.md from src/lib.rs via cargo-readme (cargo readme)
 make check/readme  # verify README.md matches the generated output
 ```
 
+Install the pinned version, not the latest. `check/readme` byte-compares the generated file, and
+cargo-readme has changed its output between releases before (3.4.0 dropped the hidden `# pub fn
+main` lines 3.3.3 kept), so a newer local install regenerates a README that fails CI with nothing
+in the diff to explain it. To move the pin deliberately, see
+`specs/design/0049-pin-cargo-readme.md`.
+
 ---
 
 ## Fixes Require Tests

CONTRIBUTING.md

@@ -8,7 +8,10 @@ Thanks for contributing!
 
 - [Rust toolchain](https://www.rust-lang.org/en-US/install.html)
 - [`cargo-readme`](https://github.com/livioribeiro/cargo-readme) (`cargo install
-  cargo-readme`)
+  cargo-readme --version 3.4.0 --locked`). Install the pinned version rather than the
+  latest: `make check/readme` byte-compares the generated file, and cargo-readme has
+  changed its output between releases, so a newer local install produces a README that
+  fails CI.
 - [GNU Make](https://www.gnu.org/software/make/)
 - [Docker](https://www.docker.com/) or another Docker-compatible container
   engine

Makefile

@@ -364,7 +364,11 @@ check/fmt:
 	@echo [$@]: Checking code format...
 	$(FMT_CC) $(FMT_CCFLAGS)
 
-# Checks if the README.md file is up-to-date
+# Checks if the README.md file is up-to-date.
+# Byte-compares against `cargo readme` output, so it is sensitive to the
+# cargo-readme version. CI installs 3.4.0 (.github/workflows/build.yml); install
+# the same one locally or this fails on a formatting difference alone. See
+# specs/design/0049-pin-cargo-readme.md to move the pin.
 check/readme:
 	@echo [$@]: Checking README.md...
 	$(README_CC) $(README_CCFLAGS) > _tmp_readme.md

specs/design/0049-pin-cargo-readme.md

@@ -1,6 +1,6 @@
 # 0049 - Pin the cargo-readme version CI installs
 
-Status: Not implemented
+Status: Implemented
 
 ## Current state
 

specs/design/README.md

@@ -67,7 +67,7 @@ the item stays here for history.
 | [0046](0046-configurable-key-replacement-policy.md) | Key replacement on overwrite is configurable, defaulting to replace | Not implemented (declined) |
 | [0047](0047-per-key-expiry-read.md) | Per-key expiry read: `CacheExpiry` / `ConcurrentCacheExpiry` | Implemented |
 | [0048](0048-ttl-overflow-vs-clamp.md) | Extreme TTL: overflow to never-expires vs clamp to a real deadline | Not implemented |
-| [0049](0049-pin-cargo-readme.md) | Pin the cargo-readme version CI installs | Not implemented |
+| [0049](0049-pin-cargo-readme.md) | Pin the cargo-readme version CI installs | Implemented |
 | [0050](0050-capability-traits-for-inherent-only-ops.md) | Capability traits for `set_max_size` and `cache_clear_with_on_evict` | Not implemented |
 | [0051](0051-cached-skip-parameter.md) | Exclude a parameter from the generated cache key | Not implemented |
 | [0052](0052-sharded-borrowed-key-lookups.md) | Borrowed-key lookups on the sharded inherent methods | Not implemented |