Skip to content

P-010 check-changelog-format: retire the rule (first retirement — sets convention) #208

@hdamker

Description

@hdamker

Problem description

P-010 check-changelog-format has no foundation in the Commonalities
or Design Guide documentation and is not derived from either audit
published with the framework design (RM#447). Its sole origin is a
single bullet in the validation detailed design:

CHANGELOG format and link tag-locking (file content analysis)

Only the "format" half was implemented — as a regex that does not
match the CAMARA per-API heading convention (## <api-name> <version>)
used by every existing repo and by the release automation's own
template. The "link tag-locking" half — the only part of that bullet
with real validation value — is not implemented at all. The rule's
dir-branch ("at least one .md file in CHANGELOG/") is trivially
satisfied by the stub CHANGELOG/README.md created by the onboarding
campaign, so the rule effectively never fires on onboarded repos.

The structural convention the rule was meant to guard is the one from
the original
CHANGELOG_TEMPLATE.md
(## API-name1 vx.y.z per-API sections). That template now lives
under documentation/deprecated/ because the release automation's
snapshot step generates the same structure automatically — the
responsibility has moved from authoring guidance to automated output.

Surfaced while preparing SimpleEdgeDiscovery r2.3 — the only context
where the flat-file branch is reachable (DEC-033 maintenance-release
fallback), and the only context where the regex bug is exposed. The
finding is a false positive because the regex cannot match CAMARA's
own convention.

Possible evolution

Retire P-010. Per the rule-metadata schema (Once assigned, never reused even if the rule is retired), the ID P-010 is reserved
permanently.

Changes:

  1. Remove the YAML entry for P-010 from
    validation/rules/python-rules.yaml so the rule stops running.
  2. Keep a header comment at the P-010 slot marking it retired: ID,
    retirement date, link to this issue, one-line rationale.
  3. Delete validation/engines/python_checks/changelog_checks.py and
    validation/tests/test_python_checks_changelog.py.
  4. No change to rule-inventory.yaml (P-010 is not listed — it is
    "un-triggerable via spec edits").

This retirement is the first in the framework and sets the convention
for future retirements.

Alternative solution

Fix the regex and keep the rule. Rejected because the underlying
concern has no documented spec, the empty-README.md case makes the
directory-mode branch vacuous, and the automation's own template now
provides the structural guarantee the rule was meant to verify — which
is why the original CHANGELOG_TEMPLATE.md was moved to
documentation/deprecated/.

Additional context

The "link tag-locking" concern bundled into the original design-doc
bullet is a separate, genuinely useful idea (catch CHANGELOG links
that point at main instead of the release tag, which break once the
next release moves content). It deserves its own issue and a new rule
ID if we decide to pursue it — it is not tied to P-010's retirement.

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions