ci: generate user-facing release notes automatically

Author: reycn

.github/scripts/publish-release.mjs

@@ -1,6 +1,7 @@
 import { execFileSync } from 'node:child_process';
-import { appendFileSync, readFileSync, statSync, mkdirSync } from 'node:fs';
+import { appendFileSync, readFileSync, statSync, mkdirSync, writeFileSync } from 'node:fs';
 import { shouldRelease, parseVersion } from './release-version.mjs';
+import { previousRelease, releaseNotes } from './release-notes.mjs';
 const gh = (...args) => execFileSync('gh', args, { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
 const api = (path) => JSON.parse(gh('api', path));
 const repo = process.env.GH_REPO,
@@ -113,6 +114,14 @@ if (
 )
   throw Error('Existing release tag points to a different commit');
 const existing = releases().find((release) => release.tag_name === tag);
+const previous = previousRelease(version, releases());
+const historyPath = previous
+  ? `repos/${repo}/compare/${encodeURIComponent(previous.tag_name)}...${sha}?per_page=100`
+  : `repos/${repo}/commits?sha=${sha}&per_page=100`;
+const pages = JSON.parse(gh('api', '--paginate', '--slurp', historyPath));
+const commits = previous ? pages.flatMap((page) => page.commits) : pages.flat().reverse();
+const notesPath = 'artifacts/release-notes.md';
+writeFileSync(notesPath, releaseNotes({ repo, version, sha, previous, commits, assets }));
 if (existing) {
   if (!existing.draft) throw Error('Release already exists');
   gh('release', 'upload', tag, ...assets, '--repo', repo, '--clobber');
@@ -128,13 +137,14 @@ if (existing) {
     sha,
     '--title',
     tag,
-    '--generate-notes',
+    '--notes-file',
+    notesPath,
     '--draft',
     ...(parseVersion(version).pre.length > 0 ? ['--prerelease'] : []),
   );
 }
 // Only make the release public after every validated package has been uploaded.
-gh('release', 'edit', tag, '--repo', repo, '--draft=false');
+gh('release', 'edit', tag, '--repo', repo, '--notes-file', notesPath, '--draft=false');
 const url = gh('release', 'view', tag, '--repo', repo, '--json', 'url', '--jq', '.url').trim();
 summary(
   `Published ${url}\n\nTested commit: ${sha}\n\nSource CI: ${run.html_url}\n\nAll six installation packages attached.`,

.github/scripts/release-notes.mjs

@@ -0,0 +1,87 @@
+import { compareVersions, parseVersion } from './release-version.mjs';
+
+export function previousRelease(version, releases) {
+  return releases
+    .filter((release) => {
+      if (release.draft) return false;
+      try {
+        return compareVersions(release.tag_name.replace(/^v/, ''), version) < 0;
+      } catch {
+        return false;
+      }
+    })
+    .sort((a, b) => compareVersions(b.tag_name.replace(/^v/, ''), a.tag_name.replace(/^v/, '')))[0];
+}
+
+const escape = (text) =>
+  Array.from(text)
+    .filter((char) => char.charCodeAt(0) >= 32 && char.charCodeAt(0) !== 127)
+    .join('')
+    .replace(/[\\`*_{}[\]<>#]/g, '\\$&');
+
+export function releaseNotes({ repo, version, sha, previous, commits, assets }) {
+  parseVersion(version);
+  const groups = { features: [], fixes: [] };
+  const seen = new Set();
+  for (const item of commits) {
+    if (seen.has(item.sha)) continue;
+    seen.add(item.sha);
+    const [subject, ...body] = item.commit.message.split('\n');
+    const match = /^(feat|fix|perf|ux|ui)(?:\([^)]*\))?!?:\s*(.+)$/i.exec(subject);
+    if (!match) continue;
+    const title = escape(match[2].trim());
+    const detail = escape(
+      body
+        .filter((line) => !/^(?:Co-authored-by|Signed-off-by|Reviewed-by):/i.test(line))
+        .join(' ')
+        .replace(/\s+/g, ' ')
+        .trim(),
+    );
+    const bullet = `- **${title}**${detail ? ` — ${detail}` : ''} ([${item.sha.slice(0, 7)}](https://github.com/${repo}/commit/${item.sha}))`;
+    groups[match[1].toLowerCase() === 'feat' ? 'features' : 'fixes'].push(bullet);
+  }
+  const count = groups.features.length + groups.fixes.length;
+  const lines = [
+    `# PDFMathReader v${version}`,
+    '',
+    count
+      ? `This release includes ${groups.features.length} new features and ${groups.fixes.length} fixes and improvements${previous ? ` since ${escape(previous.tag_name)}` : ''}. See the highlights below.`
+      : 'This release includes maintenance updates. See the full changelog for details.',
+    '',
+    `## ${version}`,
+    '',
+  ];
+  for (const [key, title] of [
+    ['features', 'New features'],
+    ['fixes', 'Fixes and improvements'],
+  ]) {
+    if (groups[key].length) lines.push(`### ${title}`, '', ...groups[key], '');
+  }
+  lines.push(
+    '## Update',
+    '',
+    'Quit PDFMathReader, download the package for your system below, replace the existing application, and reopen it. Your documents and settings are preserved.',
+    '',
+  );
+  const labels = {
+    'darwin-arm64': 'macOS Apple silicon',
+    'darwin-x64': 'macOS Intel',
+    'win32-x64': 'Windows x64',
+    'win32-ia32': 'Windows 32-bit',
+    'linux-x64': 'Linux x64',
+    'linux-armv7l': 'Linux ARMv7',
+  };
+  for (const path of assets) {
+    const name = path.split('/').at(-1);
+    const target = Object.keys(labels).find((key) => name.startsWith(`PDFMathReader-${key}.`));
+    if (!target) throw Error('Unknown release package: ' + name);
+    lines.push(
+      `- [${labels[target]}](https://github.com/${repo}/releases/download/v${version}/${encodeURIComponent(name)})`,
+    );
+  }
+  const url = previous
+    ? `https://github.com/${repo}/compare/${encodeURIComponent(previous.tag_name)}...${sha}`
+    : `https://github.com/${repo}/commits/${sha}`;
+  lines.push('', `[Full changelog](${url})`, '');
+  return lines.join('\n');
+}

.github/scripts/release-notes.test.mjs

@@ -0,0 +1,68 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { previousRelease, releaseNotes } from './release-notes.mjs';
+
+test('baseline is the highest published lower semantic version, excluding drafts', () => {
+  assert.equal(
+    previousRelease('0.2.0', [
+      { tag_name: 'v0.1.9' },
+      { tag_name: 'v0.1.10' },
+      { tag_name: 'v0.2.0-beta.1', draft: true },
+      { tag_name: 'nightly' },
+      { tag_name: 'v0.2.0' },
+      { tag_name: 'v0.3.0' },
+    ]).tag_name,
+    'v0.1.10',
+  );
+  assert.equal(previousRelease('0.1.0', []), undefined);
+});
+
+const commit = (sha, message) => ({ sha, commit: { message } });
+const options = {
+  repo: 'PDFMathTranslate/PDFMathReader',
+  version: '0.1.3',
+  sha: 'a'.repeat(40),
+  previous: { tag_name: 'v0.1.2' },
+  assets: [
+    'artifacts/PDFMathReader-darwin-arm64.zip',
+    'artifacts/PDFMathReader-linux-armv7l.tar.gz',
+  ],
+};
+test('notes group user changes, retain details, omit internal commits and trailers', () => {
+  const feature = commit(
+    'b'.repeat(40),
+    'feat(reader): Formula OCR\n\nRecognize and copy LaTeX.\n\nCo-authored-by: Bot <bot@example.com>',
+  );
+  const notes = releaseNotes({
+    ...options,
+    commits: [
+      feature,
+      feature,
+      commit('c'.repeat(40), 'ux: Improve error dialog'),
+      commit('d'.repeat(40), 'fix: Preserve preferences'),
+      commit('e'.repeat(40), 'ci: Cache dependencies'),
+      commit('f'.repeat(40), 'release: 0.1.3'),
+    ],
+  });
+  assert.match(notes, /1 new features and 2 fixes/);
+  assert.match(notes, /\*\*Formula OCR\*\* — Recognize and copy LaTeX\./);
+  assert.match(notes, /### Fixes and improvements/);
+  assert.doesNotMatch(notes, /Bot|Cache dependencies|release: 0/);
+  assert.match(notes, /releases\/download\/v0.1.3\/PDFMathReader-darwin-arm64.zip/);
+  assert.match(notes, /Linux ARMv7/);
+  assert.match(notes, /compare\/v0.1.2\.\.\.a{40}/);
+});
+test('first release and maintenance-only changes still have useful notes', () => {
+  const notes = releaseNotes({ ...options, previous: undefined, commits: [] });
+  assert.match(notes, /maintenance updates/);
+  assert.match(notes, /commits\/a{40}/);
+  assert.match(notes, /## Update/);
+});
+test('commit text cannot inject HTML or Markdown headings', () => {
+  const notes = releaseNotes({
+    ...options,
+    commits: [commit('b'.repeat(40), 'fix: <script>\n\n# heading')],
+  });
+  assert.doesNotMatch(notes, /<script>/);
+  assert.match(notes, /\\# heading/);
+});

doc/ci-release.md

@@ -59,3 +59,23 @@ fixes; bump the version again to release a fix.
 
 The packages retain the existing CI signing policy: macOS builds are unsigned
 and are not notarized. This workflow does not introduce signing credentials.
+
+## Automatic release notes
+
+CI writes the release description from commits between the highest earlier
+published semantic-version release and the exact tested commit. Draft releases
+are excluded from the baseline. The first release uses the commit history up to
+that tested commit. All history pages are included.
+
+The description contains the version, a change-count summary, **New features**
+(`feat:`), **Fixes and improvements** (`fix:`, `perf:`, `ux:`, `ui:`), update
+instructions, links to the six validated installation packages, and a full
+changelog link. Scoped prefixes such as `feat(reader):` are supported. Each
+change has a bold title and includes its commit body when provided; write
+user-facing titles and bodies to produce useful descriptions. Internal commits
+such as `ci:`, `docs:`, `chore:`, and release markers stay in the full changelog.
+No AI service or additional credentials are required.
+
+The generated description is applied both to new drafts and when retrying an
+existing draft, before making the release public. Published releases are not
+rewritten. Regression tests run as part of the release gate.