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..2be8d812 --- /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. Reason no change log is required.", +].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..4ded139b 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..9bad28be --- /dev/null +++ b/test/pr_changelog.js @@ -0,0 +1,61 @@ +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"]); + }); +});