Skip to content

Add changelog guard CI check - #369

Merged
iliaal merged 2 commits into
masterfrom
ci/changelog-guard-v2
Nov 14, 2026
Merged

iliaal merged 2 commits into
masterfrom
ci/changelog-guard-v2

Conversation

@iliaal

@iliaal iliaal commented Nov 13, 2026 •

Copy link
Copy Markdown
Owner

Before: nothing checks CHANGELOG.md, so an entry can land inside an already-released version block, or two open PRs can collide on the same heading, and it only shows up after merge.

After: a PR that touches CHANGELOG.md fails when its merge would conflict on the changelog, edit a released section, or add a duplicate ## [x], a second ### Name heading in one section or a repeated entry, including in combination with a lower-numbered open PR. Rewording, removals and new headings inside [Unreleased] are allowed.

Each failure clears without a new commit, on the PR's own Check CHANGELOG.md check: the changelog-override label (already created here) turns released-section edits into warnings; a push to master that touches CHANGELOG.md re-runs the check on every open changelog PR, so it goes red or green against the new base; a peer that closes without merging re-runs the check on the later PRs. The re-run job handles each PR separately, warns about any it can't reach, and always passes.

How: .github/scripts/changelog_guard.py diffs the base changelog against git merge-tree output. changelog_guard_test.py runs first in the job: 21 cases on throwaway repos with refs/pull/N/head refs and a stub gh that pages the PR listing and filters it by base branch, covering merge-tree, the listing, the refs/pull fetch, the re-run call, the label and peer-close remedies, and a recheck where one PR's fetch fails. changelog_guard_mutate.py deletes each rule in turn: 29 of 29 mutants fail a test.

Backtest: replayed all 17 merged PRs here that touched CHANGELOG.md, each against its merge-time base (the master commit it was merged onto), with no label: 16 of 17 pass. #334 fails (changes released section [2.0.1]) and passes with the label.

This PR doesn't touch CHANGELOG.md, so the guard step exits early here; the self-test step is what exercises it. Actions pinned by SHA, persist-credentials: false, per-job permissions (actions: write only on the re-run job); zizmor --pedantic reports no findings.


Generated by Claude Code

Fails a PR whose merge would edit a released CHANGELOG section, conflict on
the changelog, or duplicate a heading or entry, including against earlier
open PRs. A push that touches CHANGELOG.md rechecks open PRs and sets a
commit status on each instead of failing the push. The changelog-override
label allows intended released-section edits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A push to the default branch, or a peer closing unmerged, now re-runs the
guard on affected open PRs instead of setting a separate status, so the
override label, a push or a re-run clears the one check. The re-run job
keeps going past a PR it can't reach and always passes. Labels are read
from the API. Adds tests for every rule and a mutation script.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@iliaal
iliaal merged commit b8da47a into master Nov 14, 2026
41 checks passed
@iliaal
iliaal deleted the ci/changelog-guard-v2 branch November 14, 2026 14:37
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.

2 participants