M0034 readme-badges¶
Rule: The README carries a badge for the book, CI and every published crate, each linking to its target.
| Code | M0034 (stable, never reused) |
| Id | readme-badges |
| Category | repo |
| Source | spirit_level |
| Fix | exact: spl check --fix applies it |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | warn |
the top of the README tells a visitor whether the project passes and where its book, crate and API docs are |
| small-workspace | warn |
the top of the README tells a visitor whether the project passes and where its book, crate and API docs are |
| medium | warn |
the top of the README tells a visitor whether the project passes and where its book, crate and API docs are |
| big | warn |
the top of the README tells a visitor whether the project passes and where its book, crate and API docs are |
| 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, relative to the root |
workflow |
string | ".github/workflows/ci.yml" |
the CI workflow whose status badge the README shows |
Why¶
The top of the README is where a visitor decides whether the project is alive and where to read on. A row of badges answers both at a glance: the CI status of the default branch, the published version, the API docs, the book. A badge that links somewhere else, or a project that has a book nobody can find from its README, wastes that place.
What the README must carry follows from what the repo has, read from its own files:
| The repo has | Badge links to | Image |
|---|---|---|
a book with site_url in zensical.toml or mkdocs.yml |
the site_url |
any |
the CI workflow (parameter workflow) and a GitHub repository |
https://github.com/OWNER/REPO/actions/workflows/ci.yml |
that page's badge.svg |
a published crate (publish not false) |
https://crates.io/crates/NAME |
any |
| a published crate with a library | https://docs.rs/NAME |
any |
A badge is a linked image: [](link) in Markdown, or <a href="link"><img src="image"></a> in HTML. A link may go deeper than the address in the table (https://docs.rs/NAME/latest/NAME/) or carry a query (?query=branch%3Amain). Badges in code blocks and HTML comments do not count.
[](https://github.com/OWNER/REPO/actions/workflows/ci.yml)
[](https://crates.io/crates/NAME)
[](https://docs.rs/NAME)
[](https://book.example.org/)
How to fix¶
Add the badge the finding names. spl check --fix inserts it after the README's existing badges, in their form (Markdown or HTML). Without any badges, each one goes in a block of its own before the first paragraph, after a title, a logo or an HTML header; put them on consecutive lines to show them in one row. A CI badge that shows another image is changed by hand to show the workflow's badge.svg.
Configure¶
[lints.readme-badges]
level = "deny"
file = "README.md"
workflow = ".github/workflows/ci.yml"
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(readme-badges) <reason> (waivers); the code works there too, as in [lints.M0034].