Skip to content

M0012 readme-per-crate

Rule: Every crate has a README.

Code M0012 (stable, never reused)
Id readme-per-crate
Category manifest
Source spirit_level
Fix by hand

Level per tier

Tier Level Reason
small warn every crate says what it is and how to use it
small-workspace deny every crate of a workspace says what it is and what it may depend on
medium deny every crate of a workspace says what it is and what it may depend on
big deny every crate of a workspace says what it is and what it may depend on
ai off
embedded off
ui off
egui off
units-strict off
units-paranoid off

Parameters

Name Type Default Meaning
file string "README.md" the README's file name in the crate directory

Why

Every crate says what it is, what it may depend on and how to use it, in a README next to its Cargo.toml (rerun and zed both do this). It is the first thing a person or an agent opens in a crate's folder.

How to fix

Write README.md in the crate's directory: a paragraph on what it is, a line on what it may depend on, and a short example. The file name is the parameter file.

Configure

[lints.readme-per-crate]
level = "deny"
file = "README.md"
reason = "why this project wants it at this level"

Allow one finding in the code with // spirit-level: allow(readme-per-crate) <reason> (waivers); the code works there too, as in [lints.M0012].