Skip to content

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