From 8a03782f891843969a187fb9698d6ca0079b032f Mon Sep 17 00:00:00 2001 From: melbinjp Date: Wed, 19 Aug 2026 17:34:32 +0530 Subject: [PATCH] A changelogs directory is history too `changelog` has been on `_HISTORICAL_NAMES` since the fastapi measurement, where one release-notes file produced 162 findings. It could not see the plural, so `cozystack/cozystack` was reported for `docs/changelogs/v1.3.4.md` naming a controller deleted five months after that release. A changelog being a changelog. Same class of miss as the version suffix taken this morning: the rule already knows the word and cannot see an ordinary spelling of it. Measured over every clone on disk rather than taken on the one finding, because one finding is not evidence and the convention is. FOUR repositories keep a `changelogs/` directory - coolify, cozystack, ruff, uv - and twelve keep one of `changelogs/`, `release-notes/`, `releasenotes/` or `.changeset/changelogs/`. The hyphenated and unseparated forms already matched; only the plural did not. cozystack goes from 3 findings to 2, and the two that remain are real. 201 tests. --- src/docproof/config.py | 12 +++++++++++- tests/test_paths.py | 36 ++++++++++++++++++++++++++++++++++++ 2 files changed, 47 insertions(+), 1 deletion(-) diff --git a/src/docproof/config.py b/src/docproof/config.py index 8813a57..3cac695 100644 --- a/src/docproof/config.py +++ b/src/docproof/config.py @@ -47,7 +47,17 @@ # it is a statement about a past release, exactly like a changelog entry, and the only # reason it was not already caught is that "upgrading" was never on this list. _HISTORICAL_NAMES = ( - r"changelog | changes | history | news | releases? | release[-_ ]?notes" + # `changelogs?` and not `changelog`, which is the same class of miss as the version + # suffix below: the rule already knows the word and could not see an ordinary spelling of + # it. `cozystack/cozystack` was reported for `docs/changelogs/v1.3.4.md` naming a + # controller deleted five months later, which is a changelog being a changelog. + # + # Measured over every clone on disk before taking it, because one finding is not evidence + # and the convention is: **four repositories keep a `changelogs/` directory** - coolify, + # cozystack, ruff and uv - and twelve keep one of `changelogs/`, `release-notes/`, + # `releasenotes/` or `.changeset/changelogs/`. The hyphenated and unseparated forms + # already matched; only the plural did not. + r"changelogs? | changes | history | news | releases? | release[-_ ]?notes" r" | whatsnew | what[-_]s[-_]new | upgrad(?:e|ing) | migrat(?:e|ion|ing)" ) # Matches the file's own name *and* any directory on the way to it. Pillow keeps its diff --git a/tests/test_paths.py b/tests/test_paths.py index f7c087e..ca67ff3 100644 --- a/tests/test_paths.py +++ b/tests/test_paths.py @@ -883,3 +883,39 @@ def test_release_notes_are_history_even_with_the_version_in_the_name(): "README.md", ): assert not is_historical(path), path + + +def test_a_changelogs_directory_is_history_too(): + """`changelog` has been on `_HISTORICAL_NAMES` since the fastapi measurement and could not + see the plural. `cozystack/cozystack` was reported for `docs/changelogs/v1.3.4.md` naming + `internal/controller/dashboard/customformsoverride.go`, deleted five months after that + release, which is a changelog being a changelog. + + Measured over every clone on disk rather than taken on the one finding: **four keep a + `changelogs/` directory** - coolify, cozystack, ruff, uv - and twelve keep one of + `changelogs/`, `release-notes/`, `releasenotes/` or `.changeset/changelogs/`. Only the + plural was missing; the hyphenated and unseparated forms already matched. + """ + from docproof.config import is_historical + + for path in ( + "docs/changelogs/v1.3.4.md", + "changelogs/2026.md", + ".changeset/changelogs/x.md", + "docs/release-notes/8.0.md", + "docs/releasenotes/2.3.2.rst", + ): + assert is_historical(path), path + + for path in ( + "docs/changelog-policy.md", + "docs/changelogging.md", + "docs/how-we-write-changelogs.md", + "README.md", + ): + assert not is_historical(path), path + + # `src/changelogs.py` DOES match, and is left matching. The rule only ever sees + # documentation - `find_docs` yields `.md`, `.rst` and `.txt` - so a Python module named + # for changelogs never reaches this function, and the pre-existing singular had the same + # property. Asserting on an input the function cannot receive would test the test.