CHANGELOG.md duplication on every dev -> stage merge (#2466)¶
Symptom¶
CHANGELOG.md's top block (## [1.4.3](compare/v1.0.7...v1.4.3)) and the
block right below it (## [1.4.2](compare/v1.0.7...v1.4.2)) both diffed from
v1.0.7 — the last tag that actually exists. No v1.4.0/1/2 tags were ever
cut, so two consecutive dev -> stage promotions each produced a full,
overlapping diff since v1.0.7 instead of an incremental one.
Root cause¶
changelog.ymlfires on everydev -> stagemerge and runsconventional-changelog -p angular -i CHANGELOG.md -s, which always diffs from the latest existing git tag (viagit-semver-tags).- Tags are created only by
release-please.yml, which fires later, on thestage -> mainpromotion. - So every
dev -> stagemerge that happens before thatstage -> mainpromotion regenerates against the same stale tag and prepends a new full diff — it never removes the previous untagged run's entry, because the tool has no notion of "this earlier block was never released."
Options considered¶
(a) Tag at dev -> stage too (real version or a -stage.N suffix) so
conventional-changelog always has an immediately-preceding tag to diff from.
Rejected: deploy.yml triggers production image builds + ArgoCD updates on
push: tags: ["v*.*.*"]. That glob matches any string starting with v
with two further .-separated segments — including v1.4.4-stage.1 — so
every dev -> stage merge would additionally fire the prod-deploy path.
Making this safe means editing the production deploy trigger, which is an
infra/release-policy change, not a changelog fix.
(b) Drop the dev -> stage changelog job entirely, generate only at
stage -> main. Rejected on two counts:
release-please.ymlonly extracts the topCHANGELOG.mdblock for the GitHub Release body (awkbetween the first two## [x.y.z]headers) — it never generates one. Removingchangelog.ymlwith no replacement leaves stage/main release notes stale.- The release runbook (
docs/src/architecture/release-runbook.md) documents an intentional human/LLM curation window onstage, between changelog generation and thestage -> mainpromotion. Moving generation to tag-time removes that window. - A naive move (generate + commit CHANGELOG.md on
main, then tag) also risks the commit carrying[skip ci]in its message (needed to avoid re-triggeringdeploy-storybook.yml/security.ymlon themainpush) — and if the tag then points at that same commit,[skip ci]also suppressesdeploy.yml's tag-triggered production deploy, since GitHub's skip-ci check applies per commit, independent of which ref (branch or tag) is being pushed.
Fix implemented¶
Neither (a) nor (b) is a clean changelog fix — both require touching the
production deploy trigger or the documented curation workflow, which is a
release-policy call, not a CI bug fix. The actual root cause is narrower:
conventional-changelog has no way to know a previous CHANGELOG.md entry
was never released, so it stacks a new diff instead of replacing it.
.github/scripts/trim-unreleased-changelog.sh walks CHANGELOG.md's
## [x.y.z] headers top-down and drops every one whose refs/tags/vX.Y.Z
does not exist, stopping at the first that does. changelog.yml runs it
immediately before conventional-changelog. Result: each dev -> stage run
always starts from the last actually released entry, so the regenerated
diff can never overlap a previous untagged run's content — it replaces it.
No tag policy, deploy trigger, or curation timing changed. Regression test:
.github/scripts/trim-unreleased-changelog.test.sh (synthetic repo with only
v1.4.3 tagged, two untagged headers above it — asserts both are dropped and
1.4.3's content survives).
CHANGELOG.md's existing duplicate ## [1.4.2] block (fully subsumed by the
## [1.4.3] block above it — same v1.0.7 diff base, superset content) was
deleted by hand in the same commit; the script only prevents future
duplication, it doesn't retroactively clean history. Older, unrelated
oddities further down the file (duplicate 1.0.2 header, SHA-based compare
links for 1.1.1/1.0.8) were left alone — pre-existing archaeology,
not part of this bug.