Skip to content

Release notes with the version in the filename are history too - #22

Merged
melbinjp merged 1 commit into
mainfrom
historical-release-notes-with-a-version
Aug 19, 2026
Merged

Release notes with the version in the filename are history too#22
melbinjp merged 1 commit into
mainfrom
historical-release-notes-with-a-version

Conversation

@melbinjp

Copy link
Copy Markdown
Owner

release[-_ ]?notes has been on _HISTORICAL_NAMES since the fastapi measurement, where a single release-notes.md produced 162 findings, more than every other document in twenty repositories combined.

It could not see its own convention when a version was stamped on the filename. The pattern required an extension or a slash immediately after the name:

(^|/) (?: NAMES ) (?: \.[a-z0-9]+ )? (?: / | $ )

docs/release-notes.md matches. docs/release_notes_v7.9.0.md does not, because _v7.9.0 is neither.

Where it showed

enarjord/passivbot, sweep batch 10. Two of its five findings:

document says truth
docs/release_notes_v7.9.0.md:21 configs/examples/default_trailing_grid_long_npos10.json deleted in 565376e9c, four months after v7.9.0
docs/release_notes_v7.10.0.md:8 configs/examples/default_trailing_grid_long_npos7.json deleted in 71efc3c57

Both documents are correct. The config existed at the version the filename is named for, and nobody rewrites the v7.9.0 notes to track a tree they were never describing. This is the changelog argument exactly, applied to a project that keeps one file per release instead of one long file.

Pillow escapes it already, for a reason that has nothing to do with the filename: its notes live in docs/releasenotes/2.3.2.rst, and the DIRECTORY rule reads that. A project that keeps them flat got judged for identical content.

What changed, and how far

(^|/) (?: NAMES ) (?: [-_ ] v? \d+ (?: \.\d+ )* )? (?: \.[a-z0-9]+ )? (?: / | $ )

The version has to follow immediately and has to be a number. changelog-policy.md, release-notes-process.md and history-of-the-parser.md stay judged, and there are assertions on each.

Measured across every sweep batch, 147 finding lines in total: this suppresses exactly the two above and nothing else. passivbot goes from 5 broken to 3, and the three that remain are real.

197 tests.

`release[-_ ]?notes` has been on `_HISTORICAL_NAMES` since the fastapi measurement,
where one release-notes.md produced 162 findings. The pattern demanded an extension
or a slash straight after the name, so it matched `release-notes.md` and walked past
`docs/release_notes_v7.9.0.md`. A version number is neither.

enarjord/passivbot, sweep batch 10, is where it showed. Two of its five findings are
release notes naming config files deleted in later releases. Both documents are
correct: the config existed at the version the filename carries. Pillow escapes this
only because its notes live in a `releasenotes/` DIRECTORY, which the path rule
already reads; a project that keeps them flat gets judged for the same content.

Measured over every sweep batch, 147 finding lines: this suppresses exactly those two
and nothing else. Tight on purpose, so a suffix that is a word rather than a version
stays judged.

197 tests.
@melbinjp
melbinjp merged commit 3ed5461 into main Aug 19, 2026
21 checks passed
@melbinjp
melbinjp deleted the historical-release-notes-with-a-version branch August 19, 2026 10:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant