P0009 changelog-entry-length¶
Rule: A CHANGELOG entry is one short line.
| Code | P0009 (stable, never reused) |
| Id | changelog-entry-length |
| Category | prose |
| Source | spirit_level |
| Fix | by hand |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | warn |
a CHANGELOG is a list: one short line per change |
| small-workspace | warn |
a CHANGELOG is a list: one short line per change |
| medium | warn |
a CHANGELOG is a list: one short line per change |
| big | warn |
a CHANGELOG is a list: one short line per change |
| ai | deny |
a CHANGELOG is a list: one line per change |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
max-lines |
integer | 1 |
lines an entry may span |
max-words |
integer | 20 |
words an entry may have |
file |
string | "CHANGELOG.md" |
the changelog, relative to the root |
all-sections |
boolean | false |
check released sections too, not only ## [Unreleased] |
Why¶
A CHANGELOG is read as a list: what changed in this release, one line each. A long entry explains the implementation, which the book and the commits already hold, and hides the change among the words.
The rule counts the lines of each bullet under ## [Unreleased] (continuation lines included) and its words (runs of letters and digits). Released sections are left alone unless all-sections is on.
- Config: `include` key reads another file (CFG-6). <- 7 words, passes
- Added a new configuration key called include which makes it possible to
read another TOML file from the main one, merged before overrides (CFG-6). <- 2 lines, 27 words
How to fix¶
Name the change and its FEATURES id in one line. Move the explanation into the book page of the feature.
Configure¶
[lints.changelog-entry-length]
level = "deny"
max-lines = 1
max-words = 20
file = "CHANGELOG.md"
all-sections = false
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(changelog-entry-length) <reason> (waivers); the code works there too, as in [lints.P0009].