D0017 book-build-stamp¶
Rule: The book's footer shows the crate's version, commit and build age.
| Code | D0017 (stable, never reused) |
| Id | book-build-stamp |
| Category | book |
| Source | spirit_level |
| Fix | by hand |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | warn |
without a version, commit and age in the footer, a reader cannot tell which build they are looking at |
| small-workspace | warn |
without a version, commit and age in the footer, a reader cannot tell which build they are looking at |
| medium | warn |
without a version, commit and age in the footer, a reader cannot tell which build they are looking at |
| big | warn |
without a version, commit and age in the footer, a reader cannot tell which build they are looking at |
| ai | off | |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
partial |
string | "partials/copyright.html" |
the override template, relative to the theme's custom_dir, that is expected to carry the footer's build stamp |
marker |
string | "stamp" |
text that marks a build stamp in the partial, an extra_javascript file or the built site's index.html |
age-marker |
string | "ago" |
text that marks the stamp showing the build's age from the reader's own clock, beside the absolute build time |
Why¶
A reader of a built book cannot tell which version of the project they are looking at, or how stale the page is: two tabs of the same URL opened months apart look the same. exact_units' book answers this in its footer: the crate's version, the git commit it was built from (-dirty when the tree had changes) and the build time in UTC, written into a generated overrides/partials/stamp.html that overrides/partials/copyright.html includes. A small script turns the build time into the age the reader actually cares about, coarser as it grows ("built 40 s ago", "12 min ago", "3 h ago", "5 days ago"), with the absolute UTC time kept beside it.
The lint looks for this practice: an override partial (or the built site) that carries a build stamp, and a script that shows the stamp's age from the reader's own clock, not only its absolute time.
How to fix¶
Give the theme a custom_dir ([project.theme] custom_dir = "overrides" in zensical.toml), add an override partial your footer includes (partial, partials/copyright.html by default) that pulls in a generated stamp with the crate's version, commit and build time, and add a script, inline or as an extra_javascript file, that renders the build's age from Date.now(), coarser as it grows. See the pattern in exact_units (docs_ext/eu_docs_ext/stamp.py, overrides/partials/copyright.html).
Configure¶
[lints.book-build-stamp]
level = "deny"
partial = "partials/copyright.html"
marker = "stamp"
age-marker = "ago"
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(book-build-stamp) <reason> (waivers); the code works there too, as in [lints.D0017].