From 8e01a96df9c6a5742f28c19533da0a98a7cd615a Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Sat, 21 Nov 2026 02:28:05 +0000 Subject: [PATCH 1/2] Add a prepare release script scripts/prepare_release.mts takes a version, sets it in the package.json files under packages/ and plugins/, adds the pr_to_changelog.mts output to the top of CHANGELOG.md, then commits "Prepare " and tags it v. It does not push. pr_to_changelog.mts now exports generateReleaseNotes() so the output can be reused. The template comment in CHANGELOG.md is removed so the first "## " heading is always the latest release. Closes #1240 Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 31 ------------- docs/release-workflow.md | 36 ++++++--------- scripts/pr_to_changelog.mts | 52 +++++++++++++-------- scripts/prepare_release.mts | 91 +++++++++++++++++++++++++++++++++++++ test/prepare_release.js | 35 ++++++++++++++ 5 files changed, 173 insertions(+), 72 deletions(-) create mode 100644 scripts/prepare_release.mts create mode 100644 test/prepare_release.js diff --git a/CHANGELOG.md b/CHANGELOG.md index e0c787bf..cacc7195 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,36 +1,5 @@ # Changelog - - ## Version 2.1.1 ### Features diff --git a/docs/release-workflow.md b/docs/release-workflow.md index 84100618..20b7ea80 100644 --- a/docs/release-workflow.md +++ b/docs/release-workflow.md @@ -5,7 +5,8 @@ - CHANGELOG.md in the repository root - The changelog.txt file in mod directories -Pull requests will usually have suggestions for changelog entries. These can be automatically parsed and formatted by running `node scripts/pr_to_changelog.mts`, though you will have to manually sort through which should go in the changelog in the repository root and which should go in the changelogs in mod directories. +Pull requests have a changelog section that is parsed and formatted by `node scripts/pr_to_changelog.mts`. +The prepare release script below adds its output to CHANGELOG.md, but changes to mods still have to be copied into the changelogs in the mod directories by hand. If the script fails due to GitHub's 60/hour public access rate limit, you can set the `GH_TOKEN` environment variable to a fine-grained personal access token which has a much higher rate limits. @@ -15,10 +16,10 @@ The [Publish workflow](../.github/workflows/publish.yml) publishes npm packages Publishing a prerelease does not trigger it; see [GitHub's release event documentation](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#release). The npm release includes the packages under `packages/` and the six core plugins under `plugins/`. Community plugins hosted in separate repositories have independent versions and releases. -For this workflow, first merge the changelog and package version updates into `master`, then create and push the release tag on that merged commit. -Create a draft GitHub release for the existing tag and use the GitHub Release Markdown from `scripts/pr_to_changelog.mts` as its notes. +For this workflow, push the commit and tag made by `scripts/prepare_release.mts` to `master`. +Create a draft GitHub release for the existing tag and use the GitHub Release Markdown printed by `scripts/prepare_release.mts` as its notes. Publishing the draft as a stable release triggers the workflow; pushing a tag alone does not. -Preparing a release PR, pushing a tag, and publishing a release or packages are separate actions; obtain authorization for the publication steps before executing them on someone else's behalf. +Preparing a release, pushing a tag, and publishing a release or packages are separate actions; obtain authorization for the publication steps before executing them on someone else's behalf. The steps below describe publishing npm packages manually instead. > [!NOTE] @@ -33,31 +34,24 @@ The steps below describe publishing npm packages manually instead. git status ``` -2. Create a release branch and bump the version in the `package.json` files. The commands below use 2.0.1 to 2.0.2 as an example; substitute the versions for the release you are preparing. +2. Run the prepare release script with the new version. + It sets the version in the `package.json` files under `packages/` and `plugins/`, adds the changelog from merged pull requests to the top of CHANGELOG.md, commits it as "Prepare 2.0.2" and tags that commit `v2.0.2`. + Nothing is pushed. + It also prints the GitHub Release Markdown for the release notes. ```sh - git switch -c release/2.0.2 - sed -i 's/"version": "2\.0\.1"/"version": "2.0.2"/' {packages,plugins}/*/package.json - pnpm install --no-frozen-lockfile + node scripts/prepare_release.mts 2.0.2 ``` -3. Review and commit the version and changelog changes, then open and merge a release pull request. +3. Review the commit, amend it if the changelog needs edits, then push it and the tag. + If you amend the commit, move the tag with `git tag -f v2.0.2`. ```sh - git add -p - git commit -m "Prepare 2.0.2 release" + git show HEAD + git push upstream master v2.0.2 ``` -4. After the release pull request is merged, tag the merged commit and push the tag. - - ```sh - git switch master - git pull --ff-only upstream master - git tag v2.0.2 - git push upstream v2.0.2 - ``` - -5. For manual publication, perform a clean install and publish the packages. For automated publication, publish the GitHub release as described above instead. +4. For manual publication, perform a clean install and publish the packages. For automated publication, publish the GitHub release as described above instead. The repository does not track `pnpm-lock.yaml`, so allow pnpm to generate or update it during installation. diff --git a/scripts/pr_to_changelog.mts b/scripts/pr_to_changelog.mts index 4ded139b..bcaefd96 100644 --- a/scripts/pr_to_changelog.mts +++ b/scripts/pr_to_changelog.mts @@ -258,7 +258,7 @@ async function fetchStatistics(lastRelease: Release, pullRequests: Issue[]): Pro }; } -function printMarkdown( +function formatMarkdown( changelog: Changelog, issues: Issue[], users: Issue["user"][], @@ -266,12 +266,13 @@ function printMarkdown( refText: (issue: Issue) => string, userText: (user: Issue["user"]) => string, ) { + const lines: string[] = []; const sections = new Set([...changelogSections, ...Object.keys(changelog)]); for (const section of sections) { if (section in changelog) { - console.log(`### ${section}\n`); + lines.push(`### ${section}`, ""); const entries = changelog[section]; - console.log(entries.map(text => ( + lines.push(...entries.map(text => ( `- ${text.replaceAll(/#(\d+)/g, (ref, idAsText) => { const id = Number.parseInt(idAsText, 10); if (!Number.isFinite(id)) { @@ -283,27 +284,29 @@ function printMarkdown( } return refText(issue); })}` - )).join("\n")); - console.log(); + ))); + lines.push(""); } } - console.log("### Contributors\n"); - console.log(`Many thanks to the following for contributing to this release:`); - console.log(users.map(userText).join(", ")); + lines.push("### Contributors", ""); + lines.push("Many thanks to the following for contributing to this release:"); + lines.push(users.map(userText).join(", ")); const format = (value: number) => value.toLocaleString("en-US"); - console.log("\n### Statistics\n"); - console.log([ + lines.push("", "### Statistics", ""); + lines.push([ `Commits: ${format(statistics.commits)}`, `Pull Requests: ${format(statistics.pullRequests)}`, `Files Changed: ${format(statistics.filesChanged)}`, `Additions: +${format(statistics.lineAdditions)}`, `Deletions: -${format(statistics.lineDeletions)}`, ].join(" ")); + return lines.join("\n"); } -async function main() { +/** Builds the release notes for the changes merged since the last release. */ +export async function generateReleaseNotes() { const lastRelease = await fetchLastRelease(); const issues = await fetchIssuesUpdatedSince(lastRelease.created_at); @@ -314,22 +317,31 @@ async function main() { )); const changelog = changelogFromPullRequests(pullRequests, issues); - const users = [...new Map(pullRequests.map(issue => [issue.user.login, issue.user])).values()] + const users = [...new Map(pullRequests.map(issue => [issue.user.login, issue.user])).values()]; const statistics = await fetchStatistics(lastRelease, pullRequests); + return { + github: formatMarkdown(changelog, issues, users, statistics, + issue => `${repository}#${issue.number}`, + user => `@${user.login}`, + ), + changelog: formatMarkdown(changelog, issues, users, statistics, + issue => `[#${issue.number}](<${issue.html_url}>)`, + user => `[@${user.login}](<${user.html_url}>)` + ), + }; +} + +async function main() { + const notes = await generateReleaseNotes(); + console.log(); console.log("=== Github Release Markdown ==="); - printMarkdown(changelog, issues, users, statistics, - issue => `${repository}#${issue.number}`, - user => `@${user.login}`, - ); + console.log(notes.github); console.log(); console.log("=== Discord / Changelog Markdown ==="); - printMarkdown(changelog, issues, users, statistics, - issue => `[#${issue.number}](<${issue.html_url}>)`, - user => `[@${user.login}](<${user.html_url}>)` - ); + console.log(notes.changelog); } if (import.meta.main) { diff --git a/scripts/prepare_release.mts b/scripts/prepare_release.mts new file mode 100644 index 00000000..a48cbc85 --- /dev/null +++ b/scripts/prepare_release.mts @@ -0,0 +1,91 @@ +// Bumps the package versions, adds the release notes to CHANGELOG.md, then commits and tags the release. +// Usage: node scripts/prepare_release.mts +import { execFile } from "node:child_process"; +import fs from "node:fs/promises"; +import path from "node:path"; +import { promisify } from "node:util"; +import { generateReleaseNotes } from "./pr_to_changelog.mts"; + +const root = path.resolve(import.meta.dirname, ".."); +const versionPattern = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/; + +async function git(...args: string[]) { + return (await promisify(execFile)("git", args, { cwd: root, encoding: "utf8" })).stdout; +} + +export function setPackageVersion(text: string, version: string) { + const pattern = /^([ \t]*"version":[ \t]*)"[^"]*"/m; + if (!pattern.test(text)) { + throw new Error("No version field found"); + } + return text.replace(pattern, `$1"${version}"`); +} + +export function addChangelogEntry(text: string, version: string, notes: string) { + if (new RegExp(`^## Version ${version.replaceAll(".", "\\.")}$`, "m").test(text)) { + throw new Error(`CHANGELOG.md already has an entry for ${version}`); + } + const firstEntry = text.search(/^## /m); + if (firstEntry === -1) { + throw new Error("No existing entry found in CHANGELOG.md"); + } + return `${text.slice(0, firstEntry)}## Version ${version}\n\n${notes.trim()}\n\n\n${text.slice(firstEntry)}`; +} + +async function packageFiles() { + const files: string[] = []; + for (const parent of ["packages", "plugins"]) { + for (const entry of await fs.readdir(path.join(root, parent), { withFileTypes: true })) { + const file = path.join(parent, entry.name, "package.json"); + if (entry.isDirectory() && await fs.stat(path.join(root, file)).catch(() => null)) { + files.push(file); + } + } + } + return files; +} + +async function main() { + const version = process.argv[2]; + if (!version || !versionPattern.test(version)) { + console.error("Usage: node scripts/prepare_release.mts , e.g. 2.1.2"); + process.exitCode = 1; + return; + } + if (await git("status", "--porcelain", "--untracked-files=no")) { + throw new Error("Working tree has uncommitted changes"); + } + if (await git("tag", "--list", `v${version}`)) { + throw new Error(`Tag v${version} already exists`); + } + + // Done first so a GitHub API failure leaves the working tree untouched. + const notes = await generateReleaseNotes(); + const changelogPath = path.join(root, "CHANGELOG.md"); + const changelog = addChangelogEntry(await fs.readFile(changelogPath, "utf8"), version, notes.changelog); + + const files = await packageFiles(); + for (const file of files) { + const filePath = path.join(root, file); + await fs.writeFile(filePath, setPackageVersion(await fs.readFile(filePath, "utf8"), version)); + } + await fs.writeFile(changelogPath, changelog); + + await git("add", "CHANGELOG.md", ...files); + await git("commit", "--quiet", "-m", `Prepare ${version}`); + await git("tag", `v${version}`); + + console.log(); + console.log(`Committed "Prepare ${version}" and tagged it v${version}. Nothing was pushed.`); + console.log("Review it with: git show --stat HEAD"); + console.log(); + console.log("=== Github Release Markdown ==="); + console.log(notes.github); +} + +if (import.meta.main) { + main().catch(err => { + console.error(err.message ?? err); + process.exitCode = 1; + }); +} diff --git a/test/prepare_release.js b/test/prepare_release.js new file mode 100644 index 00000000..6f27a768 --- /dev/null +++ b/test/prepare_release.js @@ -0,0 +1,35 @@ +import assert from "node:assert/strict"; + +import { addChangelogEntry, setPackageVersion } from "../scripts/prepare_release.mts"; + + +describe("scripts/prepare_release", function() { + describe("setPackageVersion()", function() { + it("replaces only the package version", function() { + const text = (version) => `${JSON.stringify({ + name: "@clusterio/lib", + version, + dependencies: { a: "2.1.1" }, + }, null, "\t")}\n`; + assert.equal(setPackageVersion(text("2.1.1"), "2.2.0"), text("2.2.0")); + }); + it("throws if there is no version", function() { + assert.throws(() => setPackageVersion('{\n\t"name": "x"\n}\n', "2.2.0"), /No version field/); + }); + }); + + describe("addChangelogEntry()", function() { + const changelog = "# Changelog\n\n## Version 2.1.1\n\n### Fixes\n\n- Old fix.\n"; + + it("adds the entry above the previous release", function() { + assert.equal( + addChangelogEntry(changelog, "2.1.2", "### Fixes\n\n- New fix.\n"), + "# Changelog\n\n## Version 2.1.2\n\n### Fixes\n\n- New fix.\n\n\n" + + "## Version 2.1.1\n\n### Fixes\n\n- Old fix.\n", + ); + }); + it("throws if the version already has an entry", function() { + assert.throws(() => addChangelogEntry(changelog, "2.1.1", "- Fix."), /already has an entry/); + }); + }); +}); From 3ca203c7538dd5bdc954b13dad9806502337cc5d Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Sat, 21 Nov 2026 02:56:38 +0000 Subject: [PATCH 2/2] Stop prepare_release on changelog problems unless --force generateReleaseNotes() returns the errors and warnings from the pull request changelogs instead of printing them. prepare_release.mts lists them and aborts before touching any file, --force continues anyway. Co-Authored-By: Claude Opus 5.5 --- docs/release-workflow.md | 2 ++ scripts/pr_to_changelog.mts | 14 ++++++++++---- scripts/prepare_release.mts | 20 ++++++++++++++++---- 3 files changed, 28 insertions(+), 8 deletions(-) diff --git a/docs/release-workflow.md b/docs/release-workflow.md index 20b7ea80..c771973e 100644 --- a/docs/release-workflow.md +++ b/docs/release-workflow.md @@ -38,6 +38,8 @@ The steps below describe publishing npm packages manually instead. It sets the version in the `package.json` files under `packages/` and `plugins/`, adds the changelog from merged pull requests to the top of CHANGELOG.md, commits it as "Prepare 2.0.2" and tags that commit `v2.0.2`. Nothing is pushed. It also prints the GitHub Release Markdown for the release notes. + If a merged pull request has a missing or malformed changelog section, the script lists the problems and stops before changing anything. + Fix the pull request description and run it again, or pass `--force` to continue anyway. Entries with warnings are kept, pull requests whose changelog section could not be read are left out. ```sh node scripts/prepare_release.mts 2.0.2 diff --git a/scripts/pr_to_changelog.mts b/scripts/pr_to_changelog.mts index bcaefd96..2cb52e1e 100644 --- a/scripts/pr_to_changelog.mts +++ b/scripts/pr_to_changelog.mts @@ -195,20 +195,21 @@ export function checkPullRequestBody( function changelogFromPullRequests(pullRequests: Issue[], issues: Issue[]) { const mergedChangelog: Changelog = Object.create(null); + const problems: string[] = []; for (const pr of pullRequests) { const { changelog, error, warnings } = checkPullRequestBody(pr.body, pr, issues); if (error) { - console.error(`Failed to extract changelog in ${pr.html_url}: ${error}`) + problems.push(`Failed to extract changelog in ${pr.html_url}: ${error}`); continue; } for (const warning of warnings) { - console.warn(`Warning in changelog for ${pr.html_url}: ${warning}`) + problems.push(`Warning in changelog for ${pr.html_url}: ${warning}`); } for (const [section, items] of Object.entries(changelog)) { mergedChangelog[section] = [...mergedChangelog[section] ?? [], ...items]; } } - return mergedChangelog; + return [mergedChangelog, problems] as const; } async function fetchLastRelease() { @@ -316,11 +317,13 @@ export async function generateReleaseNotes() { && issue.pull_request.merged_at > lastRelease.created_at )); - const changelog = changelogFromPullRequests(pullRequests, issues); + const [changelog, problems] = changelogFromPullRequests(pullRequests, issues); const users = [...new Map(pullRequests.map(issue => [issue.user.login, issue.user])).values()]; const statistics = await fetchStatistics(lastRelease, pullRequests); return { + /** Errors and warnings from the pull request changelogs. */ + problems, github: formatMarkdown(changelog, issues, users, statistics, issue => `${repository}#${issue.number}`, user => `@${user.login}`, @@ -334,6 +337,9 @@ export async function generateReleaseNotes() { async function main() { const notes = await generateReleaseNotes(); + for (const problem of notes.problems) { + console.warn(problem); + } console.log(); console.log("=== Github Release Markdown ==="); diff --git a/scripts/prepare_release.mts b/scripts/prepare_release.mts index a48cbc85..a052120f 100644 --- a/scripts/prepare_release.mts +++ b/scripts/prepare_release.mts @@ -1,5 +1,6 @@ // Bumps the package versions, adds the release notes to CHANGELOG.md, then commits and tags the release. -// Usage: node scripts/prepare_release.mts +// Usage: node scripts/prepare_release.mts [--force] +// --force continues when pull request changelogs have errors or warnings. import { execFile } from "node:child_process"; import fs from "node:fs/promises"; import path from "node:path"; @@ -46,9 +47,11 @@ async function packageFiles() { } async function main() { - const version = process.argv[2]; - if (!version || !versionPattern.test(version)) { - console.error("Usage: node scripts/prepare_release.mts , e.g. 2.1.2"); + const args = process.argv.slice(2); + const force = args.includes("--force"); + const [version, ...rest] = args.filter(arg => arg !== "--force"); + if (!version || rest.length || !versionPattern.test(version)) { + console.error("Usage: node scripts/prepare_release.mts [--force] , e.g. 2.1.2"); process.exitCode = 1; return; } @@ -61,6 +64,15 @@ async function main() { // Done first so a GitHub API failure leaves the working tree untouched. const notes = await generateReleaseNotes(); + for (const problem of notes.problems) { + console.warn(problem); + } + if (notes.problems.length && !force) { + throw new Error( + `Found ${notes.problems.length} changelog problem(s) in merged pull requests. ` + + "Fix the pull request descriptions and run it again, or pass --force to continue anyway." + ); + } const changelogPath = path.join(root, "CHANGELOG.md"); const changelog = addChangelogEntry(await fs.readFile(changelogPath, "utf8"), version, notes.changelog);