diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..c91ff2ee --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,22 @@ + + +### Changelog +``` +### Features +- Added doodad to web interface. #999 + +### Changes +- ... + +### Fixes +- ... + +### Breaking Changes +- ... +``` diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml new file mode 100644 index 00000000..2430518f --- /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@v4 + with: + sparse-checkout: scripts + - uses: actions/setup-node@v4 + 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/.github/workflows/node.yml b/.github/workflows/node.yml index 80d77eff..b4bc0f7a 100644 --- a/.github/workflows/node.yml +++ b/.github/workflows/node.yml @@ -38,6 +38,8 @@ jobs: run: pnpm install --no-frozen-lockfile - name: Run tests run: pnpm --filter "@expcluster/*" run test + - name: Run script tests + run: node --test test/*.test.js - name: Run reference checks run: | # pnpm install runs prepare in dependency order, which hides missing diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 216a5196..c022444f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,6 +9,7 @@ For developers wanting to add features please follow these guidelines: - Lua is checked with [emmylua](https://github.com/EmmyLuaLs/emmylua-analyzer-rust), configured by `.emmyrc.json`. Install the EmmyLua extension rather than sumnekolua / luals, and use factoriomod-debug to generate the factorio api types. Note that an inline cast must be written `--[[@as T]]`, the spaced form is not parsed. - Changes should be made on your own fork and merged into `main` through a pull request. - Each pull request should be limited to one feature or a few bug fixes and link to the related issue page. +- Fill in the Changelog section of the pull request template, or replace its code block with `None.` and a reason. A CI check validates it and the release notes are built from it. - Pull requests are automatically linted, then built and tested against the latest clusterio `master`. - Pull requests are manually reviewed to maintain code and language quality. - New features should have the branch names: `feature/feature-name` 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/github_api.mts b/scripts/github_api.mts index 1f03a51c..12b7d7a6 100644 --- a/scripts/github_api.mts +++ b/scripts/github_api.mts @@ -11,8 +11,8 @@ export async function githubFetch( init = { ...init, headers: { - ...init.headers as Record ?? {}, "Accept": "application/vnd.github+json", + ...init.headers as Record ?? {}, } }; if (process.env.GH_TOKEN) { @@ -24,7 +24,9 @@ export async function githubFetch( console.log(response.headers); throw new Error(`GitHub replied with ${response.status} ${response.statusText}: ${await response.text()}`); } - if (!response.headers.get("Content-Type")?.startsWith("application/json")) { + const accept = init.headers!["Accept"]; + const contentType = accept === "application/vnd.github+json" ? "application/json" : accept; + if (!response.headers.get("Content-Type")?.startsWith(contentType)) { throw new Error( `GitHub replied with ${response.status} ${response.statusText}: ${response.headers.get("Content-Type")}` ); @@ -41,6 +43,15 @@ export async function githubFetchJson( return await response.json(); } +export async function githubFetchText( + path: string, + query: Record = {}, + init: RequestInit & { headers?: Record } = {}, +): Promise { + const response = await githubFetch(path, query, init); + return await response.text(); +} + export async function githubFetchJsonPaginated( path: string, query: Record = {}, @@ -117,6 +128,10 @@ export interface Release { updated_at?: string | null, } +export interface Comparison { + total_commits: number, +} + export interface Commit { sha: string, commit: { diff --git a/scripts/pr_to_changelog.mts b/scripts/pr_to_changelog.mts index 7b80b7dc..32866260 100644 --- a/scripts/pr_to_changelog.mts +++ b/scripts/pr_to_changelog.mts @@ -1,16 +1,26 @@ import { + type Comparison, type Release, type Issue, githubFetchJson, githubFetchJsonPaginated, + githubFetchText, } from "./github_api.mts"; type Changelog = Record; +type Statistics = { + commits: number, + pullRequests: number, + filesChanged: number, + lineAdditions: number, + lineDeletions: number, +}; + const repository = "explosivegaming/ExpCluster"; const branch = "main"; -const changelogSections = [ +export const changelogSections = [ "Major Features", "Features", "Fixes", @@ -69,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); @@ -87,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[] = []; @@ -110,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; @@ -122,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) { @@ -147,26 +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}: No body`) - console.log(pr.title) + 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}`) - console.log(pr.title) - console.log(pr.body) - continue; - } - const [changelog, warnings] = parseChangelog(createParser(changelogLines), pr, issues); for (const warning of warnings) { console.warn(`Warning in changelog for ${pr.html_url}: ${warning}`) } @@ -180,7 +214,7 @@ function changelogFromPullRequests(pullRequests: Issue[], issues: Issue[]) { async function fetchLastRelease() { // Assumes releases are ordered by their creation or tag time in descending order. const releases = await githubFetchJson(`/repos/${repository}/releases`); - const latest = releases[0] + const latest = releases.find(r => r.target_commitish === branch); if (!latest) { throw new Error(`Unable to find latest release on ${branch}`); } @@ -194,10 +228,41 @@ async function fetchIssuesUpdatedSince(since: string) { ); } +async function fetchStatistics(lastRelease: Release, pullRequests: Issue[]): Promise { + const path = `/repos/${repository}/compare/${lastRelease.tag_name}...${branch}`; + const comparison = await githubFetchJson(path, { per_page: "1" }); + // The JSON response lists at most 300 files, the diff has all of them. + const diff = await githubFetchText(path, {}, { headers: { "Accept": "application/vnd.github.diff" } }); + let filesChanged = 0; + let lineAdditions = 0; + let lineDeletions = 0; + let inHunk = false; // Skips the ---/+++ file headers + for (const line of diff.split("\n")) { + if (line.startsWith("diff --git ")) { + filesChanged += 1; + inHunk = false; + } else if (line.startsWith("@@")) { + inHunk = true; + } else if (inHunk && line.startsWith("+")) { + lineAdditions += 1; + } else if (inHunk && line.startsWith("-")) { + lineDeletions += 1; + } + } + return { + commits: comparison.total_commits, + pullRequests: pullRequests.length, + filesChanged, + lineAdditions, + lineDeletions, + }; +} + function printMarkdown( changelog: Changelog, issues: Issue[], users: Issue["user"][], + statistics: Statistics, refText: (issue: Issue) => string, userText: (user: Issue["user"]) => string, ) { @@ -223,8 +288,19 @@ function printMarkdown( } } + console.log("### Contributors\n"); console.log(`Many thanks to the following for contributing to this release:`); - console.log(users.map(userText).join("\n")) + console.log(users.map(userText).join(", ")); + + const format = (value: number) => value.toLocaleString("en-US"); + console.log("\n### Statistics\n"); + console.log([ + `Commits: ${format(statistics.commits)}`, + `Pull Requests: ${format(statistics.pullRequests)}`, + `Files Changed: ${format(statistics.filesChanged)}`, + `Additions: +${format(statistics.lineAdditions)}`, + `Deletions: -${format(statistics.lineDeletions)}`, + ].join(" ")); } async function main() { @@ -239,17 +315,18 @@ async function main() { const changelog = changelogFromPullRequests(pullRequests, issues); const users = [...new Map(pullRequests.map(issue => [issue.user.login, issue.user])).values()] + const statistics = await fetchStatistics(lastRelease, pullRequests); console.log(); console.log("=== Github Release Markdown ==="); - printMarkdown(changelog, issues, users, + printMarkdown(changelog, issues, users, statistics, issue => `${repository}#${issue.number}`, user => `@${user.login}`, ); console.log(); console.log("=== Discord / Changelog Markdown ==="); - printMarkdown(changelog, issues, users, + printMarkdown(changelog, issues, users, statistics, issue => `[#${issue.number}](<${issue.html_url}>)`, user => `[@${user.login}](<${user.html_url}>)` ); diff --git a/test/pr_changelog.test.js b/test/pr_changelog.test.js new file mode 100644 index 00000000..00a6d319 --- /dev/null +++ b/test/pr_changelog.test.js @@ -0,0 +1,62 @@ +import assert from "node:assert/strict"; +import { describe, it } from "node:test"; + +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/explosivegaming/ExpCluster/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"]); + }); +});