Merge pull request #1226 from bbassie/ci/changelog-check

Check the changelog section of pull request descriptions in CI
This commit is contained in:
Cooldude2606 authored and GitHub committed 2026-11-18 13:12:39 +00:00
commit d42d9d3743
4 files changed
+205 -16

No files matched your search

+30
View File
@@ -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
+71
View File
@@ -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("<", "&lt;")}`),
"",
rules,
"Edit the description and this check runs again. Expected format:",
"",
"````markdown",
expectedFormat,
"````",
"",
].join("\n"));
}
process.exitCode = 1;
}
if (import.meta.main) {
main();
}
+43 -16
View File
@@ -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}`)
}
+61
View File
@@ -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"]);
});
});