Two stage contracts mandate a changelog entry and list it under Outputs:
ICM/express-change/stages/01-change/CONTEXT.md, process step 5 - "and add the CHANGELOG.md
entry"ICM/process-plan/stages/04-documentation/CONTEXT.md, process step 1 - "Add the CHANGELOG.md
entry under [unreleased], typed per Keep a Changelog"
No gate checks either one.
What it cost
In venv-axi, PR #33 - the larger of the two
merges in that release - landed with no changelog entry at all. It surfaced only in a manual
pre-release review three commits later, and correcting it needed a dedicated backfill plan,
plans/pre-release-record-repair.md,
run through express-change just to repair the record. Writing a plan to fix a hole in the record
is the failure mode the methodology exists to prevent.
This issue rests on the plugin's own stated principle, from the Maintenance section of the README:
All four exist because the corresponding contract was previously stated and unenforced, which is
the same thing as absent.
Proposed fix
Extend gate_closeout.py, which already walks uncommitted plans and already knows which ones sit
at status: done. When one does, require either that CHANGELOG.md is itself uncommitted, or
that it already names the plan slug.
That reuses machinery that is entirely present, adds no new event, and fires at the one moment the
omission is still free to fix - before the session ends and the branch is pushed.
Found while running icm@icm-spec v1.0.0 through the venv-axi
v0.2.0 release cycle.
Two stage contracts mandate a changelog entry and list it under Outputs:
ICM/express-change/stages/01-change/CONTEXT.md, process step 5 - "and add theCHANGELOG.mdentry"
ICM/process-plan/stages/04-documentation/CONTEXT.md, process step 1 - "Add theCHANGELOG.mdentry under
[unreleased], typed per Keep a Changelog"No gate checks either one.
What it cost
In
venv-axi, PR #33 - the larger of the twomerges in that release - landed with no changelog entry at all. It surfaced only in a manual
pre-release review three commits later, and correcting it needed a dedicated backfill plan,
plans/pre-release-record-repair.md,run through
express-changejust to repair the record. Writing a plan to fix a hole in the recordis the failure mode the methodology exists to prevent.
This issue rests on the plugin's own stated principle, from the Maintenance section of the README:
Proposed fix
Extend
gate_closeout.py, which already walks uncommitted plans and already knows which ones sitat
status: done. When one does, require either thatCHANGELOG.mdis itself uncommitted, orthat it already names the plan slug.
That reuses machinery that is entirely present, adds no new event, and fires at the one moment the
omission is still free to fix - before the session ends and the branch is pushed.
Found while running
icm@icm-specv1.0.0 through thevenv-axiv0.2.0 release cycle.