Skip to content

fix: seed an empty CHANGELOG.md so the first release is well-formed - #5

Merged
robinbowes merged 1 commit into
mainfrom
fix/changelog-seed-heading
Aug 28, 2026
Merged

fix: seed an empty CHANGELOG.md so the first release is well-formed#5
robinbowes merged 1 commit into
mainfrom
fix/changelog-seed-heading

Conversation

@robinbowes

Copy link
Copy Markdown
Collaborator

The generated 0.1.0 notes on #1 end with a stray ## Changelog heading below the release entries. It is not a release-please bug — it is the seed content.

src/updaters/changelog.ts treats any pre-existing content as prior changelog body when it finds no version heading in it, demoting H1 to H2 and appending it below the new entry:

if(lastEntryIndex===-1){if(content){return`${this.header()}\n${this.changelogEntry}\n\n${adjustHeaders(content).trim()}\n`;}else{return`${this.header()}\n${this.changelogEntry}\n`;}}// adjustHeaders: content.replace(/^#(\s)/gm, '##$1')

So a seed of # Changelog becomes ## Changelog, parked under the first release's entries, where it then persists for the life of the file. An empty seed takes the second branch and is clean.

bootstrap seeded that heading into every generated project, so the defect propagated rather than being local to this repo — yo61/gh-release-stats carries the same artifact on main at line 36, from its own first release. yo61/unifictl does not, which is consistent with its changelog having been seeded differently.

Changes

  • bootstrap writes an empty CHANGELOG.md instead of printf '# Changelog\n', with the reasoning recorded at the call site.
  • This repo's own CHANGELOG.md is emptied so the pending 0.1.0 release is well-formed.

Not touched: the artifact already committed to gh-release-stats. Removing it there is a separate, cosmetic change to a shipped file.

Verification

Generated a project from this branch with ./bootstrap --defaults and confirmed its CHANGELOG.md is 0 bytes, then ran the updater's exact logic over both seeds:

seed '# Changelog' -> ends with a stray "## Changelog" (1 occurrence)
seed empty -> clean (0 occurrences)

./scripts/test-bootstrap.sh passes both the flat and DDD cases; shellcheck and shfmt -i 2 -bn -ci -sr clean.

release-please's Changelog updater treats any pre-existing content as
prior changelog body when it finds no version heading in it. It demotes
H1 to H2 and appends the result below the new entry
(src/updaters/changelog.ts):
if (lastEntryIndex === -1) {
if (content) {
return `${header()}\n${entry}\n\n${adjustHeaders(content).trim()}\n`;
} else {
return `${header()}\n${entry}\n`;
}
}
Seeding `# Changelog` therefore produces a stray `## Changelog` heading
below the first release's entries, which then persists for the life of
the file. Confirmed against the generated 0.1.0 notes on the Release PR,
and yo61/gh-release-stats carries the same artifact on main from its own
first release.
bootstrap seeded that heading into every generated project, so the defect
propagated. Seed an empty file instead, which takes the updater's clean
branch, and empty this repo's own CHANGELOG.md so 0.1.0 is well-formed.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AwbmT2rzfYtPqoHPMPWLZt

@yo61-lastlightyo61-lastlightBot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PR removes the pre-seeded changelog heading from both the template and this repository, and the bootstrap reset now leaves CHANGELOG.md empty so release-please can generate the first changelog without demoting a seed heading. I found no blocking correctness or contract issues in the changed paths.

@robinbowes
robinbowes merged commit 9c291ab into mainAug 28, 2026
10 checks passed
@robinbowes
robinbowes deleted the fix/changelog-seed-heading branch August 28, 2026 14:51
Sign up for freeto 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.

1 participant

@robinbowes