From d9db1460cc3dad7608c84a158dc5191a22b3cc0e Mon Sep 17 00:00:00 2001
From: Robin Bowes <robin@yo61.com>
Date: Fri, 28 Aug 2026 15:45:27 +0100
Subject: [PATCH] fix: seed an empty CHANGELOG.md so the first release is
 well-formed

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
---
 CHANGELOG.md | 1 -
 bootstrap    | 9 +++++++--
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 825c32f..e69de29 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1 +0,0 @@
-# Changelog
diff --git a/bootstrap b/bootstrap
index ac31e81..5f506df 100755
--- a/bootstrap
+++ b/bootstrap
@@ -138,9 +138,14 @@ sed -i.bak "s|^$PROJECT_NAME = \"$PACKAGE_NAME.cli:main\"|$cli_name_esc = \"$PAC
 
 git mv "src/pythontemplate" "src/$PACKAGE_NAME"
 
-# Reset release state.
+# Reset release state. CHANGELOG.md is emptied, not seeded with a heading:
+# release-please's Changelog updater treats any pre-existing content as prior
+# changelog body when it finds no version heading, so it demotes `# Changelog`
+# to `## Changelog` and appends it below the first release's entry
+# (src/updaters/changelog.ts, adjustHeaders). An empty file takes the clean
+# branch instead.
 printf '{".":"0.0.0"}\n' > .release-please-manifest.json
-printf '# Changelog\n' > CHANGELOG.md
+: > CHANGELOG.md
 
 # Template-only content must not propagate into the generated project: the
 # design records, and the smoke test that drives ./bootstrap -- which is about