chore: the changelog has an owner at both moments

Entries are written with the change (a warning-level CodeRabbit
pre-merge check nudges PRs that alter user-visible behavior), and
release-time promotion is owned by make sync-version alongside every
other version stamp: it turns [Unreleased] into a dated section,
retargets the compare links, refuses an empty [Unreleased], and is
idempotent. RELEASING.md documents both moments.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: mstrathman

.coderabbit.yaml

@@ -114,6 +114,17 @@ reviews:
       requirements: >-
         Conventional-commit style prefix (feat/fix/docs/bench/site/chore/
         refactor/test/ci) with a concise, specific subject.
+    custom_checks:
+      - name: "Changelog entry for user-visible changes"
+        mode: "warning"
+        instructions: >-
+          If the PR changes user-visible behavior (SQL surface, option
+          keys, error codes, defaults, output formats, packaging), it
+          should add an entry under CHANGELOG.md's [Unreleased] section
+          in the same PR. Refactors, docs, tests, benchmarks, and CI
+          changes do not need one. Release-time promotion of
+          [Unreleased] into a dated section is owned by make
+          sync-version; PRs should never do that themselves.
 
 chat:
   auto_reply: true

RELEASING.md

@@ -6,6 +6,11 @@ committing, and tagging.
 
 ## Cut a release
 
+0. Make sure `CHANGELOG.md`'s `[Unreleased]` section reflects the
+   release. Entries are written with the changes themselves (a
+   user-visible change adds its line in the same PR); this step is only
+   a review that nothing is missing.
+
 1. Sync every manifest to the new version:
 
    ```sh
@@ -16,8 +21,12 @@ committing, and tagging.
    `bindings/python/pyproject.toml` (PEP 440 form, e.g. `0.0.1-alpha.5`
    becomes `0.0.1a5`), `bindings/python/sqlite_predict/__init__.py`
    (`__version__`), and `bindings/node/package.json` (including the
-   per-platform `optionalDependencies` pins). The C header derives its
-   version from `VERSION` at build time and needs no edit.
+   per-platform `optionalDependencies` pins), and promotes
+   `CHANGELOG.md`'s `[Unreleased]` section into a dated `[<version>]`
+   section with updated compare links. It refuses to run if
+   `[Unreleased]` is empty, so a release cannot ship without notes. The
+   C header derives its version from `VERSION` at build time and needs
+   no edit.
 
 2. Commit the version bump.
 

scripts/sync-version.mjs

@@ -65,4 +65,43 @@ for (const d of deps) pkg.optionalDependencies[d] = version;
 fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
 console.log(`  bindings/node/package.json -> ${version} (+ ${deps.length} optionalDependencies)`);
 
+/* Promote CHANGELOG's [Unreleased] into a dated section for this version.
+ * Idempotent: if the section already exists, leave the file alone. The
+ * changelog itself is written with the change; this owns only the
+ * release-time promotion, like every other version stamp here. */
+const clPath = path.join(root, "CHANGELOG.md");
+let cl = fs.readFileSync(clPath, "utf8");
+if (cl.includes(`## [${version}]`)) {
+  console.log(`  CHANGELOG.md already has a [${version}] section`);
+} else {
+  if (!/## \[Unreleased\]\n/.test(cl)) {
+    console.error("CHANGELOG.md has no [Unreleased] section to promote");
+    process.exit(1);
+  }
+  const unreleasedBody = cl
+    .split("## [Unreleased]\n")[1]
+    .split(/\n## \[/)[0]
+    .trim();
+  if (!unreleasedBody) {
+    console.error(`CHANGELOG.md [Unreleased] is empty; write the release's
+entries before running sync-version`);
+    process.exit(1);
+  }
+  const date = new Date().toISOString().slice(0, 10);
+  cl = cl.replace("## [Unreleased]\n",
+                  `## [Unreleased]\n\n## [${version}] - ${date}\n`);
+  /* retarget the compare links: Unreleased diffs from the new tag, and the
+   * new tag diffs from the previous one (the old Unreleased base). */
+  const linkRe = /^\[Unreleased\]: (.*)\/compare\/(v[^.]+[^ ]*)\.\.\.HEAD$/m;
+  const lm = cl.match(linkRe);
+  if (lm) {
+    const [, repo, prevTag] = lm;
+    cl = cl.replace(linkRe,
+      `[Unreleased]: ${repo}/compare/v${version}...HEAD\n` +
+      `[${version}]: ${repo}/compare/${prevTag}...v${version}`);
+  }
+  fs.writeFileSync(clPath, cl);
+  console.log(`  CHANGELOG.md -> [${version}] - ${date}`);
+}
+
 console.log(`VERSION = ${version}  (PyPI: ${pv})`);