Dedupe fragment-summary vs conventional-commit subject at the CHANGELOG generation layer #258

New issue

Closed

opened 2026-06-29 12:53:41 +02:00 by quartermaster · 0 comments

quartermaster commented

2026-06-29 12:53:41 +02:00

Owner

Empirical anchor

tmux-tell#630 (first-ever release-toolkit-driven cut, v0.23.0) surfaced this on Surveyor's re-review at fresh HEAD post-#633 rebase: the v0.23.0 cut listed #623 TWICE in ## [0.23.0] ### Fixed —

The fragment prose from changelog.d/623.fixed.md (rich OOM-cascade narrative)
A bullet - **mutation**: cap --workers=4 ... (#623) emitted by the conventional-commit-subject parser, from the fix(mutation): ... (#623) commit

The CHANGELOG renderer composes BOTH sources without deduplication. Manual dedup IS prescribed in docs/conventions.md §"When to use which":

No deduplication in v0.1... both entries appear. Review the prep PR + dedupe manually.

But manual dedup DOES NOT SURVIVE rolling-PR regenerate-on-rebase semantics: every push to main triggers release-prep regeneration on the rolling PR, which re-emits the conventional-commit-subject bullets, which wipes any prior manual dedup. So an adopter's dedup-→merge sequence MUST be ephemeral-protected by tight sequencing (last edit before merge) with no subsequent rebase.

tmux-tell#630 had to dedupe TWICE in the same PR session: first at 7473468 after the initial Surveyor catch, wiped by the #633 rebase, then again at 73ae5fe after the regeneration re-emitted the bullet. The convention works AS DOCUMENTED but only on linear cut paths, not on regenerate-on-rebase paths.

Durable fix path (this tracker)

Generation-layer dedup: when composing the CHANGELOG section for a cut, after emitting fragment summaries + conventional-commit-subject bullets, check for (#NNN) issue references that appear in BOTH sources. For duplicates:

Prefer the fragment prose (richer narrative) over the conventional-commit bullet
Emit a one-line debug log so the dedup is auditable
Document the dedup-precedence in docs/conventions.md (replacing the current "manual dedup" guidance)

This eliminates the manual-dedup-wipe cycle for all consumers, not just the first-cut adopter.

Composition

Companion to release-toolkit#257 (release-bot PAT — eliminates the release-bot push doesn't trigger CI class)
4th of 4 first-toolkit-cut substrate gaps surfaced by tmux-tell#630:
1. release-toolkit#257 — release-bot push doesn't trigger CI (system-token anti-recursion)
2. tmux-tell#632 — workflow_dispatch escape hatch (consumer-side; shipped)
3. tmux-tell#633 — check-changelog-placement skip regex (consumer-side; shipped)
4. This issue — fragment-vs-commit generation-layer dedup (toolkit-side)

Three of four are consumer-side adopter-gotchas + worth a docs/integration.md "common adopter gotchas" section. The toolkit-side ones (#257 + this issue) are the durable fixes that eliminate the gotchas at the source.

What this issue does NOT do

Does NOT touch the existing conventional-commit-subject parser (its emission is fine; the dedup is post-emission)
Does NOT remove the docs/conventions.md "manual dedup" guidance immediately — leave as fallback until this lands
Does NOT fix the current tmux-tell#630 cut (the manual dedup at 73ae5fe is the bridge)

Refs

tmux-tell#630 (empirical anchor — manual dedup wipe observed twice in one PR session)
release-toolkit#257 (sibling gap: release-bot PAT)
tmux-tell#632 (sibling gap: workflow_dispatch escape hatch; merged)
tmux-tell#633 (sibling gap: check-changelog-placement skip regex; merged)
docs/conventions.md §"When to use which" (the manual-dedup guidance that motivated this)
Surveyor 3120 (the framing that surfaced "manual dedup doesn't survive regenerate-on-rebase")

priority/medium · size/M (generation-layer + docs update + bats test for the dedup precedence)

## Empirical anchor tmux-tell#630 (first-ever release-toolkit-driven cut, v0.23.0) surfaced this on Surveyor's re-review at fresh HEAD post-#633 rebase: the v0.23.0 cut listed `#623` TWICE in `## [0.23.0] ### Fixed` — 1. The fragment prose from `changelog.d/623.fixed.md` (rich OOM-cascade narrative) 2. A bullet `- **mutation**: cap --workers=4 ... (#623)` emitted by the conventional-commit-subject parser, from the `fix(mutation): ... (#623)` commit The CHANGELOG renderer composes BOTH sources without deduplication. Manual dedup IS prescribed in `docs/conventions.md` §"When to use which": > No deduplication in v0.1... both entries appear. Review the prep PR + dedupe manually. **But manual dedup DOES NOT SURVIVE rolling-PR regenerate-on-rebase semantics**: every push to main triggers release-prep regeneration on the rolling PR, which re-emits the conventional-commit-subject bullets, which wipes any prior manual dedup. So an adopter's dedup-→merge sequence MUST be ephemeral-protected by tight sequencing (last edit before merge) with no subsequent rebase. tmux-tell#630 had to dedupe TWICE in the same PR session: first at 7473468 after the initial Surveyor catch, wiped by the #633 rebase, then again at 73ae5fe after the regeneration re-emitted the bullet. The convention works AS DOCUMENTED but only on linear cut paths, not on regenerate-on-rebase paths. ## Durable fix path (this tracker) Generation-layer dedup: when composing the CHANGELOG section for a cut, after emitting fragment summaries + conventional-commit-subject bullets, check for `(#NNN)` issue references that appear in BOTH sources. For duplicates: - Prefer the fragment prose (richer narrative) over the conventional-commit bullet - Emit a one-line debug log so the dedup is auditable - Document the dedup-precedence in `docs/conventions.md` (replacing the current "manual dedup" guidance) This eliminates the manual-dedup-wipe cycle for all consumers, not just the first-cut adopter. ## Composition - Companion to release-toolkit#257 (release-bot PAT — eliminates the release-bot push doesn't trigger CI class) - 4th of 4 first-toolkit-cut substrate gaps surfaced by tmux-tell#630: 1. release-toolkit#257 — release-bot push doesn't trigger CI (system-token anti-recursion) 2. tmux-tell#632 — workflow_dispatch escape hatch (consumer-side; shipped) 3. tmux-tell#633 — `check-changelog-placement` skip regex (consumer-side; shipped) 4. This issue — fragment-vs-commit generation-layer dedup (toolkit-side) Three of four are consumer-side adopter-gotchas + worth a `docs/integration.md` "common adopter gotchas" section. The toolkit-side ones (#257 + this issue) are the durable fixes that eliminate the gotchas at the source. ## What this issue does NOT do - Does NOT touch the existing conventional-commit-subject parser (its emission is fine; the dedup is post-emission) - Does NOT remove the `docs/conventions.md` "manual dedup" guidance immediately — leave as fallback until this lands - Does NOT fix the current tmux-tell#630 cut (the manual dedup at 73ae5fe is the bridge) ## Refs - tmux-tell#630 (empirical anchor — manual dedup wipe observed twice in one PR session) - release-toolkit#257 (sibling gap: release-bot PAT) - tmux-tell#632 (sibling gap: workflow_dispatch escape hatch; merged) - tmux-tell#633 (sibling gap: check-changelog-placement skip regex; merged) - docs/conventions.md §"When to use which" (the manual-dedup guidance that motivated this) - Surveyor 3120 (the framing that surfaced "manual dedup doesn't survive regenerate-on-rebase") priority/medium · size/M (generation-layer + docs update + bats test for the dedup precedence)