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].