read CHANGELOG.md for commit/tag/release body

If a CHANGELOG.md is present with a heading for the new version, use its body
instead of a `git log` summary. Heading matching is lenient. If the heading
has no date or a placeholder (YYYY-MM-DD, xxxx-xx-xx, etc.), rewrite it to
today's date and include the file in the commit.

Closes #48

Co-Authored-By: Claude (Opus 4.7) <noreply@anthropic.com>

Author: silverwind

README.md

@@ -61,6 +61,10 @@ To automatically sign commits and tags created by `versions` with GPG add this t
 
 By default, `versions` pushes the commit and tag to `origin` after creating them. Pass `--no-push` to skip the push and keep changes local. Use `--remote` and `--branch` to override the target remote and branch.
 
+## Changelog
+
+If a `CHANGELOG.md` is present at the project root with a heading for the new version, its body is used as the commit message, tag annotation, and release body. Heading matching is lenient — `# 1.2.3`, `## v1.2.3`, `## [1.2.3]`, `## [1.2.3] - 2024-01-15`, `## 1.2.3 (YYYY-MM-DD)` all work. If the heading has no date or a placeholder (`YYYY-MM-DD`, `xxxx-xx-xx`, etc.), it gets rewritten to today's date and included in the commit. With no matching entry, the tool falls back to a `git log` summary.
+
 ## Creating releases
 
 When using the `--release` option, `versions` will automatically create a GitHub or Gitea release after pushing the tag. The release body will contain the same changelog as the commit message. `--release` requires the push and is incompatible with `--no-push`.

index.test.ts

@@ -8,6 +8,7 @@ import {
   readVersionFromPackageJson, readVersionFromPyprojectToml,
   removeIgnoredFiles, getGithubTokens, getGiteaTokens,
   getRepoInfo, writeResult, createForgeRelease,
+  readChangelogEntry, updateChangelogHeadingDate,
   type RepoInfo,
 } from "./index.ts";
 import {exec, tomlGetString, SubprocessError} from "./utils.ts";
@@ -374,6 +375,71 @@ snapshots:
   expect(await readFile(join(tmpDir, "pnpm-lock.yaml"), "utf8")).toEqual(lockContent);
 }));
 
+test("readChangelogEntry", () => {
+  const md = `# Changelog
+
+## [Unreleased]
+
+## [1.2.3] - 2024-01-15
+### Added
+- new thing
+
+### Fixed
+- broken thing
+
+## 1.2.2 (2024-01-01)
+- prior
+
+## v1.2.1
+old
+`;
+  expect(readChangelogEntry(md, "1.2.3")).toEqual("### Added\n- new thing\n\n### Fixed\n- broken thing");
+  expect(readChangelogEntry(md, "1.2.2")).toEqual("- prior");
+  expect(readChangelogEntry(md, "1.2.1")).toEqual("old");
+  expect(readChangelogEntry(md, "v1.2.3")).toEqual("### Added\n- new thing\n\n### Fixed\n- broken thing");
+  expect(readChangelogEntry(md, "9.9.9")).toBeNull();
+
+  expect(readChangelogEntry("# 1.0.0\n\nbody\n", "1.0.0")).toEqual("body");
+  expect(readChangelogEntry("# 1.0.0\n\nbody\n", "1.0.10")).toBeNull();
+  expect(readChangelogEntry("## 1.0.0\n## 1.0.1\nb\n", "1.0.0")).toBeNull();
+  expect(readChangelogEntry("## 1.0.0-rc.1\n\nrc\n## 1.0.0\n\nrelease\n", "1.0.0")).toEqual("release");
+  expect(readChangelogEntry("## 1.0.0\n\nrelease\n## 1.0.0-rc.1\n\nrc\n", "1.0.0-rc.1")).toEqual("rc");
+  expect(readChangelogEntry("# Changelog\n\n## 1.0.0\nbody\n", "1.0.0")).toEqual("body");
+  expect(readChangelogEntry("", "1.0.0")).toBeNull();
+});
+
+test("updateChangelogHeadingDate", () => {
+  const today = "2026-04-30";
+
+  expect(updateChangelogHeadingDate("## 1.2.3\n\nbody\n", "1.2.3", today))
+    .toEqual("## 1.2.3 - 2026-04-30\n\nbody\n");
+
+  expect(updateChangelogHeadingDate("## [1.2.3]\n\nbody\n", "1.2.3", today))
+    .toEqual("## [1.2.3] - 2026-04-30\n\nbody\n");
+
+  expect(updateChangelogHeadingDate("## 1.2.3 - YYYY-MM-DD\n\nbody\n", "1.2.3", today))
+    .toEqual("## 1.2.3 - 2026-04-30\n\nbody\n");
+
+  expect(updateChangelogHeadingDate("## [1.2.3] (yyyy-mm-dd)\n\nbody\n", "1.2.3", today))
+    .toEqual("## [1.2.3] (2026-04-30)\n\nbody\n");
+
+  expect(updateChangelogHeadingDate("## 1.2.3 - xxxx-xx-xx\n\nbody\n", "1.2.3", today))
+    .toEqual("## 1.2.3 - 2026-04-30\n\nbody\n");
+
+  expect(updateChangelogHeadingDate("## 1.2.3 - XXXX-XX-XX\n\nbody\n", "1.2.3", today))
+    .toEqual("## 1.2.3 - 2026-04-30\n\nbody\n");
+
+  expect(updateChangelogHeadingDate("## 1.2.3 - DD-MM-YYYY\n\nbody\n", "1.2.3", today))
+    .toEqual("## 1.2.3 - 2026-04-30\n\nbody\n");
+
+  expect(updateChangelogHeadingDate("## 1.2.3 - ????-??-??\n\nbody\n", "1.2.3", today))
+    .toEqual("## 1.2.3 - 2026-04-30\n\nbody\n");
+
+  expect(updateChangelogHeadingDate("## [1.2.3] - 2024-01-15\n\nbody\n", "1.2.3", today)).toBeNull();
+
+  expect(updateChangelogHeadingDate("## 1.0.0\nbody\n", "9.9.9", today)).toBeNull();
+});
+
 test("createForgeRelease github success", async () => {
   const mock = vi.fn(() => Promise.resolve(Response.json({html_url: "https://github.com/o/r/releases/tag/1.0.1"}, {status: 201})));
   stubGlobal("fetch", mock);
@@ -1042,6 +1108,62 @@ test("incrementSemver unknown level throws", () => {
   expect(() => incrementSemver("1.0.0", "unknown")).toThrow("Invalid semver level");
 });
 
+test("CHANGELOG.md drives commit body and gets dated heading", () => withTmpDir(async (tmpDir) => {
+  await writeFile(join(tmpDir, "package.json"), JSON.stringify({name: "test-pkg", version: "1.0.0"}, null, 2));
+  await writeFile(join(tmpDir, "CHANGELOG.md"), `# Changelog\n\n## [1.0.1]\n- Fixed thing X\n- Added thing Y\n\n## 1.0.0\nold stuff\n`);
+
+  const {env} = await setupReleaseRepo(tmpDir);
+  const opts = {cwd: tmpDir, env: {...process.env, ...env}};
+
+  await exec("node", [distPath, "--no-push", "patch", "package.json"], opts);
+
+  const today = new Date().toISOString().substring(0, 10);
+  const changelogAfter = await readFile(join(tmpDir, "CHANGELOG.md"), "utf8");
+  expect(changelogAfter).toContain(`## [1.0.1] - ${today}`);
+
+  const {stdout: msg} = await exec("git", ["log", "-1", "--pretty=%B"], opts);
+  expect(msg).toContain("- Fixed thing X");
+  expect(msg).toContain("- Added thing Y");
+  // git log fallback (commit subjects) must not leak in
+  expect(msg).not.toContain("Initial commit");
+}));
+
+test("CHANGELOG.md without entry falls back to git log", () => withTmpDir(async (tmpDir) => {
+  await writeFile(join(tmpDir, "package.json"), JSON.stringify({name: "test-pkg", version: "1.0.0"}, null, 2));
+  await writeFile(join(tmpDir, "CHANGELOG.md"), `# Changelog\n\n## 1.0.0\nold\n`);
+
+  const {env} = await setupReleaseRepo(tmpDir);
+  const opts = {cwd: tmpDir, env: {...process.env, ...env}};
+
+  // commit between the tag and HEAD so the git log fallback has something to report
+  await writeFile(join(tmpDir, "package.json"), JSON.stringify({name: "test-pkg", version: "1.0.0", changed: true}, null, 2));
+  await exec("git", ["commit", "-am", "tweak something"], opts);
+
+  await exec("node", [distPath, "--no-push", "patch", "package.json"], opts);
+
+  // unchanged because no entry for 1.0.1
+  expect(await readFile(join(tmpDir, "CHANGELOG.md"), "utf8")).toEqual(`# Changelog\n\n## 1.0.0\nold\n`);
+
+  const {stdout: msg} = await exec("git", ["log", "-1", "--pretty=%B"], opts);
+  expect(msg).toContain("tweak something");
+}));
+
+test("CHANGELOG.md with existing date is left alone", () => withTmpDir(async (tmpDir) => {
+  await writeFile(join(tmpDir, "package.json"), JSON.stringify({name: "test-pkg", version: "1.0.0"}, null, 2));
+  const original = `# Changelog\n\n## [1.0.1] - 2024-01-15\n- existing entry\n`;
+  await writeFile(join(tmpDir, "CHANGELOG.md"), original);
+
+  const {env} = await setupReleaseRepo(tmpDir);
+  const opts = {cwd: tmpDir, env: {...process.env, ...env}};
+
+  await exec("node", [distPath, "--no-push", "patch", "package.json"], opts);
+
+  expect(await readFile(join(tmpDir, "CHANGELOG.md"), "utf8")).toEqual(original);
+
+  const {stdout: msg} = await exec("git", ["log", "-1", "--pretty=%B"], opts);
+  expect(msg).toContain("- existing entry");
+}));
+
 test("readVersionFromPackageJson", () => withTmpDir(async (tmpDir) => {
   await writeFile(join(tmpDir, "package.json"), JSON.stringify({name: "test", version: "3.2.1"}, null, 2));
   expect(readVersionFromPackageJson(tmpDir)).toEqual("3.2.1");

index.ts

@@ -14,6 +14,7 @@ const reSemver = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d
 const rePrereleaseVersion = /^(\d+)\.(\d+)\.(\d+)(?:-([a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*))?/;
 const rePrereleaseIdNum = /^([a-zA-Z0-9-]+)\.(\d+)$/;
 const reDatePattern = /(?<=[^0-9]|^)[0-9]{4}-[0-9]{2}-[0-9]{2}(?=[^0-9]|$)/g;
+const reDate = new RegExp(reDatePattern.source);
 const reReplaceString = /^s#([^#]+)#([^#]+)#(.*)$/;
 
 function stripV(str: string): string {
@@ -93,6 +94,56 @@ export function readVersionFromPyprojectToml(projectRoot: string): string | null
   });
 }
 
+const reHeading = /^(#+)\s+(.*?)\s*$/;
+// Three groups of 2-4 chars from Y/M/D/X/? separated by `-`, `/`, `.`, or whitespace.
+// Covers YYYY-MM-DD, xxxx-xx-xx, ????-??-??, DD-MM-YYYY, YYYY/MM/DD etc.
+const rePlaceholderDate = /[YMDX?]{2,4}[-/. ][YMDX?]{2,4}[-/. ][YMDX?]{2,4}/i;
+
+function findVersionHeading(lines: string[], version: string): {index: number, level: number} | null {
+  // Non-version-char boundaries so "1.2.3" doesn't match "1.2.30" or "1.2.3-rc.1".
+  const re = new RegExp(`(?:^|[^\\d.\\-])v?${esc(stripV(version))}(?:[^\\d.\\-]|$)`, "i");
+  for (let i = 0; i < lines.length; i++) {
+    const m = reHeading.exec(lines[i]);
+    if (m && re.test(m[2])) return {index: i, level: m[1].length};
+  }
+  return null;
+}
+
+// Lenient about heading shape: matches "# 1.2.3", "## v1.2.3", "## [1.2.3]",
+// "## [1.2.3] - 2024-01-15", "## 1.2.3 (2024-01-15)", etc.
+export function readChangelogEntry(content: string, version: string): string | null {
+  const lines = content.split(reNewline);
+  const head = findVersionHeading(lines, version);
+  if (!head) return null;
+
+  let end = lines.length;
+  for (let i = head.index + 1; i < lines.length; i++) {
+    const m = reHeading.exec(lines[i]);
+    if (m && m[1].length <= head.level) {
+      end = i;
+      break;
+    }
+  }
+
+  return lines.slice(head.index + 1, end).join("\n").trim() || null;
+}
+
+export function updateChangelogHeadingDate(content: string, version: string, date: string): string | null {
+  const lines = content.split(reNewline);
+  const head = findVersionHeading(lines, version);
+  if (!head) return null;
+
+  const heading = lines[head.index];
+  if (rePlaceholderDate.test(heading)) {
+    lines[head.index] = heading.replace(rePlaceholderDate, date);
+  } else if (reDate.test(heading)) {
+    return null;
+  } else {
+    lines[head.index] = `${heading.trimEnd()} - ${date}`;
+  }
+  return lines.join("\n");
+}
+
 export async function removeIgnoredFiles(files: Array<string>, cwd?: string): Promise<Array<string>> {
   let result: Result;
   try {
@@ -358,7 +409,8 @@ async function main(): Promise<void> {
     end();
   }
 
-  const date = args.date ? new Date().toISOString().substring(0, 10) : "";
+  const today = new Date().toISOString().substring(0, 10);
+  const date = args.date ? today : "";
 
   const pwd = cwd();
   const gitDir = findUp(".git", pwd);
@@ -465,8 +517,28 @@ async function main(): Promise<void> {
   const msgs = (args.message || []).filter(msg => typeof msg === "string");
   const tagName = args["prefix"] ? `v${newVersion}` : newVersion;
 
-  const filesToAddPromise = (!args.gitless && !args.all && files.length) ? removeIgnoredFiles(files) : null;
+  const changelogInfo = (() => {
+    const path = findUp("CHANGELOG.md", projectRoot);
+    if (!path) return null;
+    let original: string;
+    try {
+      original = readFileSync(path, "utf8");
+    } catch {
+      return null;
+    }
+    const entry = readChangelogEntry(original, newVersion);
+    if (!entry) return null;
+    return {path, entry, original, updated: updateChangelogHeadingDate(original, newVersion, today)};
+  })();
+
+  const allFiles = changelogInfo?.updated ? [...files, relative(pwd, changelogInfo.path)] : files;
+  const filesToAddPromise = (!args.gitless && !args.all && allFiles.length) ? removeIgnoredFiles(allFiles) : null;
   const changelogPromise = (!args.gitless && !args.dry) ? (async () => {
+    if (changelogInfo) {
+      logVerbose(`using changelog entry from ${changelogInfo.path}`);
+      return changelogInfo.entry;
+    }
+
     let range = "";
     const tagExists = await exec("git", ["rev-parse", "--verify", `refs/tags/${tagName}`]).then(() => true, () => false);
     if (tagExists) {
@@ -508,23 +580,28 @@ async function main(): Promise<void> {
   const rollbacks: Array<() => Promise<void> | void> = [];
 
   try {
-    if (files.length) {
-      const originals = new Map<string, string>();
-      rollbacks.push(() => {
-        for (const [file, content] of originals) write(file, content);
-      });
-      for (const file of files) {
-        const [filePath, newData, oldData] = getFileChanges({file, baseVersion, newVersion, replacements, date});
-        if (newData !== null) {
-          if (!originals.has(filePath)) originals.set(filePath, oldData!);
-          logVerbose(`writing ${filePath}`);
-          write(filePath, newData);
-        } else {
-          logVerbose(`skipping ${file} (unhandled lockfile)`);
-        }
+    const originals = new Map<string, string>();
+    rollbacks.push(() => {
+      for (const [file, content] of originals) write(file, content);
+    });
+    for (const file of files) {
+      const [filePath, newData, oldData] = getFileChanges({file, baseVersion, newVersion, replacements, date});
+      if (newData !== null) {
+        if (!originals.has(filePath)) originals.set(filePath, oldData!);
+        logVerbose(`writing ${filePath}`);
+        write(filePath, newData);
+      } else {
+        logVerbose(`skipping ${file} (unhandled lockfile)`);
       }
     }
 
+    if (changelogInfo?.updated) {
+      const {path, original, updated} = changelogInfo;
+      if (!originals.has(path)) originals.set(path, original);
+      logVerbose(`updating heading date in ${path}`);
+      write(path, updated);
+    }
+
     if (typeof args.command === "string") {
       logVerbose(`running command: ${args.command}`);
       writeResult(await exec(args.command, [], {shell: true}));