From 3d1ca990273928193e9f7125f75f7c4df0f46b8c Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Tue, 17 Nov 2026 12:08:06 +0000 Subject: [PATCH 1/3] Check the changelog section of pull request descriptions in CI The check runs the same parser as scripts/pr_to_changelog.mts, so a description that passes CI is one the release script accepts. Checks that need the GitHub API (issue references existing, pointing at this pull request) still only run at release time. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/changelog.yml | 30 ++++++++++++++ scripts/check_pr_changelog.mts | 71 +++++++++++++++++++++++++++++++++ scripts/pr_to_changelog.mts | 59 +++++++++++++++++++-------- test/pr_changelog.js | 59 +++++++++++++++++++++++++++ 4 files changed, 203 insertions(+), 16 deletions(-) create mode 100644 .github/workflows/changelog.yml create mode 100644 scripts/check_pr_changelog.mts create mode 100644 test/pr_changelog.js diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml new file mode 100644 index 00000000..5a538b49 --- /dev/null +++ b/.github/workflows/changelog.yml @@ -0,0 +1,30 @@ +name: Changelog + +on: + pull_request: + types: [opened, edited, synchronize, reopened] + +permissions: + contents: read + +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number }} + cancel-in-progress: true + +jobs: + check: + # Bot pull requests do not fill in the template. + if: github.event.pull_request.user.type != 'Bot' + runs-on: ubuntu-latest + timeout-minutes: 5 + steps: + - uses: actions/checkout@v7 + with: + sparse-checkout: scripts + - uses: actions/setup-node@v7 + with: + node-version: 24.x + - name: Check changelog in pull request description + env: + PR_BODY: ${{ github.event.pull_request.body }} + run: node scripts/check_pr_changelog.mts diff --git a/scripts/check_pr_changelog.mts b/scripts/check_pr_changelog.mts new file mode 100644 index 00000000..83b460bb --- /dev/null +++ b/scripts/check_pr_changelog.mts @@ -0,0 +1,71 @@ +// Checks the changelog section of a pull request body, read from the PR_BODY environment variable. +import fs from "node:fs"; +import { checkPullRequestBody, changelogSections } from "./pr_to_changelog.mts"; + +const expectedFormat = [ + "### Changelog", + "```", + "### Features", + "- Added doodad to web interface. #123", + "", + "### Fixes", + "- Fixed doodad not showing up. #456", + "```", + "", + "Or, when nothing user facing changed, replace the code block with:", + "", + "### Changelog", + "None. Only changes CI configuration.", +].join("\n"); + +/** Returns the problems found in the body, an empty list means it is valid. */ +export function findChangelogProblems(body: string | null | undefined) { + const { error, warnings } = checkPullRequestBody(body); + return error ? [error] : warnings; +} + +function escapeAnnotation(text: string) { + return text.replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A"); +} + +function main() { + const problems = findChangelogProblems(process.env.PR_BODY); + const summaryPath = process.env.GITHUB_STEP_SUMMARY; + if (!problems.length) { + console.log("Changelog section is valid."); + if (summaryPath) { + fs.appendFileSync(summaryPath, "Changelog section is valid.\n"); + } + return; + } + + for (const problem of problems) { + console.log(`::error title=Invalid changelog::${escapeAnnotation(problem)}`); + } + const rules = `Valid sections are ${changelogSections.join(", ")}. ` + + "Each entry must reference an issue, or this pull request if there is no issue."; + console.log(`\n${rules}`); + console.log(`Expected format in the pull request description:\n\n${expectedFormat}`); + if (summaryPath) { + fs.appendFileSync(summaryPath, [ + "## Invalid changelog", + "", + "The changelog section of the pull request description has problems:", + "", + ...problems.map(problem => `- ${problem.replaceAll("<", "<")}`), + "", + rules, + "Edit the description and this check runs again. Expected format:", + "", + "````markdown", + expectedFormat, + "````", + "", + ].join("\n")); + } + process.exitCode = 1; +} + +if (import.meta.main) { + main(); +} diff --git a/scripts/pr_to_changelog.mts b/scripts/pr_to_changelog.mts index 9fe18305..8b474779 100644 --- a/scripts/pr_to_changelog.mts +++ b/scripts/pr_to_changelog.mts @@ -20,7 +20,7 @@ type Statistics = { const repository = "clusterio/clusterio"; const branch = "master"; -const changelogSections = [ +export const changelogSections = [ "Major Features", "Features", "Fixes", @@ -79,7 +79,7 @@ function extractPullRequestChangelog( { const headerFail = skipToLine(parser, /^###? Changelog *$/); if (headerFail) { - return [failure, , "Header not found"]; + return [failure, , "### Changelog header not found"]; } parser.pos += 1; skipEmptyLines(parser); @@ -97,10 +97,19 @@ function extractPullRequestChangelog( if (blockEndFail) { return [failure, , "End of code block not found after header"]; } - return [success, parser.lines.slice(blockStartPos, parser.pos)]; + const lines = parser.lines.slice(blockStartPos, parser.pos); + if (!lines.some(line => line.trim() !== "")) { + return [failure, , "Code block is empty, replace it with None. if nothing applies"]; + } + return [success, lines]; } -function parseChangelog(parser: ParserState, pr: Issue, issues: Issue[]): [Changelog, string[]] { +/** Pass no issues to skip the checks that need the GitHub API. */ +function parseChangelog( + parser: ParserState, + pr?: Issue, + issues?: Issue[], +): [Changelog, string[]] { let section: string | undefined; let changelog: Changelog = Object.create(null); let warnings: string[] = []; @@ -120,6 +129,10 @@ function parseChangelog(parser: ParserState, pr: Issue, issues: Issue[]): [Chang changelog[section] = changelog[section] ?? []; continue; } + if (!section && /^None/i.test(line)) { + warnings.push(`"${line}" on line ${parser.pos} must replace the code block, not sit inside it`); + continue; + } if (!section) { warnings.push(`Unexpected content "${line}" outside of a changelog section on line ${parser.pos}`); continue; @@ -132,6 +145,9 @@ function parseChangelog(parser: ParserState, pr: Issue, issues: Issue[]): [Chang let hasRef = false for (const ref of entry.matchAll(/#(\d+)/g)) { hasRef = true; + if (!issues || !pr) { + continue; + } const id = Number.parseInt(ref[1], 10); const refIssue = issues.find(issue => issue.number === id); if (!refIssue) { @@ -157,23 +173,34 @@ function parseChangelog(parser: ParserState, pr: Issue, issues: Issue[]): [Chang return [changelog, warnings]; } +export function checkPullRequestBody( + body: string | null | undefined, + pr?: Issue, + issues?: Issue[], +): { changelog: Changelog, error?: string, warnings: string[] } { + if (!body) { + return { changelog: Object.create(null), error: "Pull request has no body", warnings: [] }; + } + const [ + changelogFail, + changelogLines, + changelogFailReason + ] = extractPullRequestChangelog(createParser(body.split(/\r?\n/))); + if (changelogFail) { + return { changelog: Object.create(null), error: changelogFailReason, warnings: [] }; + } + const [changelog, warnings] = parseChangelog(createParser(changelogLines), pr, issues); + return { changelog, warnings }; +} + function changelogFromPullRequests(pullRequests: Issue[], issues: Issue[]) { const mergedChangelog: Changelog = Object.create(null); for (const pr of pullRequests) { - if (!pr.body) { - console.error(`Failed to extract changelog in ${pr.html_url}: Pull request has no body`); + const { changelog, error, warnings } = checkPullRequestBody(pr.body, pr, issues); + if (error) { + console.error(`Failed to extract changelog in ${pr.html_url}: ${error}`) continue; } - const [ - changelogFail, - changelogLines, - changelogFailReason - ] = extractPullRequestChangelog(createParser(pr.body.split(/\r?\n/))); - if (changelogFail) { - console.error(`Failed to extract changelog in ${pr.html_url}: ${changelogFailReason}`) - continue; - } - const [changelog, warnings] = parseChangelog(createParser(changelogLines), pr, issues); for (const warning of warnings) { console.warn(`Warning in changelog for ${pr.html_url}: ${warning}`) } diff --git a/test/pr_changelog.js b/test/pr_changelog.js new file mode 100644 index 00000000..aedf67a9 --- /dev/null +++ b/test/pr_changelog.js @@ -0,0 +1,59 @@ +import assert from "node:assert/strict"; + +import { checkPullRequestBody } from "../scripts/pr_to_changelog.mts"; +import { findChangelogProblems } from "../scripts/check_pr_changelog.mts"; + + +describe("scripts/check_pr_changelog", function() { + function body(...lines) { + return ["Description.", "", "### Changelog", ...lines].join("\r\n"); + } + + it("accepts entries in a code block", function() { + const text = body( + "```", + "### Features", + "- Added doodad. #12", + "", + "### Fixes", + "- Fixed [#13](https://github.com/clusterio/clusterio/issues/13)", + "```", + ); + assert.deepEqual(findChangelogProblems(text), []); + assert.deepEqual({ ...checkPullRequestBody(text).changelog }, { + "Features": ["Added doodad. #12"], + "Fixes": ["Fixed #13"], + }); + }); + it("accepts None. in place of the code block", function() { + assert.deepEqual(findChangelogProblems(body("", "None. Only changes CI.")), []); + }); + it("rejects a missing body or section", function() { + assert.deepEqual(findChangelogProblems(null), ["Pull request has no body"]); + assert.deepEqual(findChangelogProblems("Description only."), ["### Changelog header not found"]); + assert.deepEqual(findChangelogProblems(body("Text")), ["Code block not found after header"]); + assert.deepEqual(findChangelogProblems(body("```", "### Fixes")), ["End of code block not found after header"]); + assert.deepEqual(findChangelogProblems(body("```", "", "```")), [ + "Code block is empty, replace it with None. if nothing applies", + ]); + }); + it("rejects None. inside the code block", function() { + assert.deepEqual(findChangelogProblems(body("```", "None.", "```")), [ + "\"None.\" on line 1 must replace the code block, not sit inside it", + ]); + }); + it("rejects malformed entries", function() { + const text = body("```", "- Orphan #1", "### Bugs", "- Fixed it", "Loose text", "```"); + assert.deepEqual(findChangelogProblems(text), [ + "Unexpected content \"- Orphan #1\" outside of a changelog section on line 1", + "Changelog section Bugs on line 2 is not one of " + + "Major Features, Features, Fixes, Changes, Breaking Changes, Meta", + "Changelog entry on line 3 does not reference an issue", + "Unexpected content \"Loose text\" on line 4", + ]); + }); + it("rejects the unedited template", function() { + const text = body("```", "### Features", "- Added doodad to web interface. #999", "", "### Changes", "- ...", "```"); + assert.deepEqual(findChangelogProblems(text), ["Changelog entry on line 5 does not reference an issue"]); + }); +}); From cd7c850a16e61382ab3a3bf908f97427c63d0934 Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Tue, 17 Nov 2026 12:09:53 +0000 Subject: [PATCH 2/3] Match the CI lint style in the changelog check Co-Authored-By: Claude Opus 5.5 --- scripts/check_pr_changelog.mts | 4 ++-- test/pr_changelog.js | 8 +++++--- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/scripts/check_pr_changelog.mts b/scripts/check_pr_changelog.mts index 83b460bb..1a6969bd 100644 --- a/scripts/check_pr_changelog.mts +++ b/scripts/check_pr_changelog.mts @@ -42,8 +42,8 @@ function main() { for (const problem of problems) { console.log(`::error title=Invalid changelog::${escapeAnnotation(problem)}`); } - const rules = `Valid sections are ${changelogSections.join(", ")}. ` - + "Each entry must reference an issue, or this pull request if there is no issue."; + const rules = `Valid sections are ${changelogSections.join(", ")}. ` + + "Each entry must reference an issue, or this pull request if there is no issue."; console.log(`\n${rules}`); console.log(`Expected format in the pull request description:\n\n${expectedFormat}`); if (summaryPath) { diff --git a/test/pr_changelog.js b/test/pr_changelog.js index aedf67a9..034bdab7 100644 --- a/test/pr_changelog.js +++ b/test/pr_changelog.js @@ -46,14 +46,16 @@ describe("scripts/check_pr_changelog", function() { const text = body("```", "- Orphan #1", "### Bugs", "- Fixed it", "Loose text", "```"); assert.deepEqual(findChangelogProblems(text), [ "Unexpected content \"- Orphan #1\" outside of a changelog section on line 1", - "Changelog section Bugs on line 2 is not one of " - + "Major Features, Features, Fixes, Changes, Breaking Changes, Meta", + "Changelog section Bugs on line 2 is not one of " + + "Major Features, Features, Fixes, Changes, Breaking Changes, Meta", "Changelog entry on line 3 does not reference an issue", "Unexpected content \"Loose text\" on line 4", ]); }); it("rejects the unedited template", function() { - const text = body("```", "### Features", "- Added doodad to web interface. #999", "", "### Changes", "- ...", "```"); + const text = body( + "```", "### Features", "- Added doodad to web interface. #999", "", "### Changes", "- ...", "```", + ); assert.deepEqual(findChangelogProblems(text), ["Changelog entry on line 5 does not reference an issue"]); }); }); From c2e08540d00c586df0ec5ade62121f4dbcfb22cb Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Wed, 18 Nov 2026 13:05:29 +0000 Subject: [PATCH 3/3] Quote the expected text in changelog check messages Co-Authored-By: Claude Opus 5.5 --- scripts/check_pr_changelog.mts | 2 +- scripts/pr_to_changelog.mts | 4 ++-- test/pr_changelog.js | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/scripts/check_pr_changelog.mts b/scripts/check_pr_changelog.mts index 1a6969bd..2be8d812 100644 --- a/scripts/check_pr_changelog.mts +++ b/scripts/check_pr_changelog.mts @@ -15,7 +15,7 @@ const expectedFormat = [ "Or, when nothing user facing changed, replace the code block with:", "", "### Changelog", - "None. Only changes CI configuration.", + "None. Reason no change log is required.", ].join("\n"); /** Returns the problems found in the body, an empty list means it is valid. */ diff --git a/scripts/pr_to_changelog.mts b/scripts/pr_to_changelog.mts index 8b474779..4ded139b 100644 --- a/scripts/pr_to_changelog.mts +++ b/scripts/pr_to_changelog.mts @@ -79,7 +79,7 @@ function extractPullRequestChangelog( { const headerFail = skipToLine(parser, /^###? Changelog *$/); if (headerFail) { - return [failure, , "### Changelog header not found"]; + return [failure, , "\"### Changelog\" header not found"]; } parser.pos += 1; skipEmptyLines(parser); @@ -99,7 +99,7 @@ function extractPullRequestChangelog( } const lines = parser.lines.slice(blockStartPos, parser.pos); if (!lines.some(line => line.trim() !== "")) { - return [failure, , "Code block is empty, replace it with None. if nothing applies"]; + return [failure, , "Code block is empty, replace it with \"None.\" if nothing applies"]; } return [success, lines]; } diff --git a/test/pr_changelog.js b/test/pr_changelog.js index 034bdab7..9bad28be 100644 --- a/test/pr_changelog.js +++ b/test/pr_changelog.js @@ -30,11 +30,11 @@ describe("scripts/check_pr_changelog", function() { }); it("rejects a missing body or section", function() { assert.deepEqual(findChangelogProblems(null), ["Pull request has no body"]); - assert.deepEqual(findChangelogProblems("Description only."), ["### Changelog header not found"]); + assert.deepEqual(findChangelogProblems("Description only."), ["\"### Changelog\" header not found"]); assert.deepEqual(findChangelogProblems(body("Text")), ["Code block not found after header"]); assert.deepEqual(findChangelogProblems(body("```", "### Fixes")), ["End of code block not found after header"]); assert.deepEqual(findChangelogProblems(body("```", "", "```")), [ - "Code block is empty, replace it with None. if nothing applies", + "Code block is empty, replace it with \"None.\" if nothing applies", ]); }); it("rejects None. inside the code block", function() {