fix: rewrite changelog updater for Keep a Changelog format

Avoid duplicate [Unreleased] headings and keep the preamble intact when
preparing releases. Add unit tests and harden release workflow output.

Author: eddietejeda

.github/workflows/release.yml

@@ -37,10 +37,11 @@ jobs:
           else
             body="Release ${version}."
           fi
+          delimiter="EOF_${RANDOM}_${RANDOM}"
           {
-            echo "body<<EOF"
+            echo "body<<${delimiter}"
             echo "$body"
-            echo "EOF"
+            echo "${delimiter}"
           } >> "$GITHUB_OUTPUT"
 
       - name: Create GitHub Release

scripts/release.sh

@@ -95,57 +95,7 @@ update_changelog() {
   local ver="$1"
   local date
   date="$(date +%Y-%m-%d)"
-  python3 - "$ver" "$date" <<'PY'
-import re, sys
-from pathlib import Path
-
-ver, date = sys.argv[1], sys.argv[2]
-path = Path("CHANGELOG.md")
-
-if not path.exists():
-    path.write_text(
-        "# Changelog\n\n"
-        "All notable changes to this project will be documented in this file.\n\n"
-        "The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),\n"
-        "and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n"
-        f"## [Unreleased]\n\n"
-        f"## [{ver}] - {date}\n\n"
-        "### Changed\n\n"
-        f"- Release {ver}\n"
-    )
-    raise SystemExit(0)
-
-text = path.read_text()
-if re.search(rf"^## \[{re.escape(ver)}\]", text, re.M):
-    raise SystemExit(0)
-
-unreleased = re.search(r"^## \[Unreleased\]\s*\n(.*?)(?=^## \[|\Z)", text, re.M | re.S)
-if unreleased and unreleased.group(1).strip():
-    body = unreleased.group(1).rstrip() + "\n"
-    text = re.sub(r"^## \[Unreleased\]\s*\n.*?(?=^## \[|\Z)", "", text, count=1, flags=re.M | re.S)
-    insert = f"## [Unreleased]\n\n## [{ver}] - {date}\n{body}\n"
-    if text.startswith("# Changelog"):
-        parts = text.split("\n\n", 2)
-        if len(parts) >= 2:
-            text = parts[0] + "\n\n" + parts[1] + "\n\n" + insert + (parts[2] if len(parts) > 2 else "")
-        else:
-            text = insert + text
-    else:
-        text = insert + text
-else:
-    insert = (
-        f"## [Unreleased]\n\n"
-        f"## [{ver}] - {date}\n\n"
-        "### Changed\n\n"
-        f"- Release {ver}\n\n"
-    )
-    if "## [Unreleased]" in text:
-        text = text.replace("## [Unreleased]", insert.strip() + "\n\n## [Unreleased]", 1)
-    else:
-        text = re.sub(r"(^# Changelog.*?)(\n\n|\Z)", r"\1\n\n" + insert, text, count=1, flags=re.S)
-
-path.write_text(text)
-PY
+  python3 scripts/update_changelog.py "$ver" "$date"
 }
 
 cmd_prepare() {

scripts/update_changelog.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""Update CHANGELOG.md for a new release version."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+
+def update_changelog_text(text: str, ver: str, date: str) -> str:
+    if re.search(rf"^## \[{re.escape(ver)}\]", text, re.M):
+        return text
+
+    unreleased = re.search(r"^## \[Unreleased\]\s*\n(.*?)(?=^## \[|\Z)", text, re.M | re.S)
+    if unreleased:
+        body = unreleased.group(1).strip()
+        if body:
+            section = f"## [{ver}] - {date}\n\n{body}\n\n"
+        else:
+            section = (
+                f"## [{ver}] - {date}\n\n"
+                "### Changed\n\n"
+                f"- Release {ver}\n\n"
+            )
+        return re.sub(
+            r"^(## \[Unreleased\]\s*\n)(.*?)(?=^## \[|\Z)",
+            lambda match: match.group(1) + "\n" + section,
+            text,
+            count=1,
+            flags=re.M | re.S,
+        )
+
+    section = (
+        f"## [Unreleased]\n\n"
+        f"## [{ver}] - {date}\n\n"
+        "### Changed\n\n"
+        f"- Release {ver}\n\n"
+    )
+    first_heading = re.search(r"^## \[", text, re.M)
+    if first_heading:
+        pos = first_heading.start()
+        return text[:pos] + section + text[pos:]
+    return text.rstrip() + "\n\n" + section
+
+
+def update_changelog_file(path: Path, ver: str, date: str) -> None:
+    if not path.exists():
+        path.write_text(
+            "# Changelog\n\n"
+            "All notable changes to this project will be documented in this file.\n\n"
+            "The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),\n"
+            "and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n"
+            f"## [Unreleased]\n\n"
+            f"## [{ver}] - {date}\n\n"
+            "### Changed\n\n"
+            f"- Release {ver}\n"
+        )
+        return
+
+    path.write_text(update_changelog_text(path.read_text(), ver, date))
+
+
+def main() -> None:
+    if len(sys.argv) != 3:
+        raise SystemExit("usage: update_changelog.py VERSION YYYY-MM-DD")
+    update_changelog_file(Path("CHANGELOG.md"), sys.argv[1], sys.argv[2])
+
+
+if __name__ == "__main__":
+    main()

tests/test_update_changelog.py

@@ -0,0 +1,37 @@
+from scripts.update_changelog import update_changelog_text
+
+HEADER = """# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-05-19
+
+### Added
+
+- Initial feature.
+"""
+
+
+def test_empty_unreleased_inserts_version_without_duplicate_heading():
+    result = update_changelog_text(HEADER, "0.1.2", "2026-05-20")
+    assert result.count("## [Unreleased]") == 1
+    assert "## [0.1.2] - 2026-05-20" in result
+    assert "The format is based on [Keep a Changelog]" in result.split("## [0.1.2]")[0]
+    assert result.index("## [0.1.2]") < result.index("## [0.1.1]")
+
+
+def test_populated_unreleased_moves_notes_into_new_section():
+    text = HEADER.replace(
+        "## [Unreleased]\n\n",
+        "## [Unreleased]\n\n### Added\n\n- New widget.\n\n",
+    )
+    result = update_changelog_text(text, "0.1.2", "2026-05-20")
+    assert result.count("## [Unreleased]") == 1
+    assert "- New widget." in result
+    assert result.index("- New widget.") < result.index("## [0.1.1]")
+    assert "The format is based on [Keep a Changelog]" in result.split("## [0.1.2]")[0]