Add a prepare release script (#1244)

* 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 <version>" and tags it
v<version>. 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 <noreply@anthropic.com>

* 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 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Cooldude2606andClaude Opus 5.5 authored and GitHub committed 2026-11-21 03:05:03 +00:00
commit 2bba4a8ccd
5 files changed
+197 -76

No files matched your search

-31
View File
@@ -1,36 +1,5 @@
# Changelog
<!-- Template for entries. Add sections that apply as changes are made.
## Version 2.0.0-alpha.xx
### Major Features
- Major additions and/or major improvements to managing clusters.
### Features
- New features added.
### Changes
- Small changes to existing behaviour.
### Fixes
- Bugfixes
### Breaking Changes
- Changes which break backwards compatibility with older hosts or plugins code.
### Meta
- Changes to the project activities / structure worth highlighting but have no impact on the published package.
Many thanks to the following for contributing to this release:
[@username](https://github.com/username)
-->
## Version 2.1.1
### Features
+17 -21
View File
@@ -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,26 @@ 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.
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
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.
+42 -24
View File
@@ -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() {
@@ -258,7 +259,7 @@ async function fetchStatistics(lastRelease: Release, pullRequests: Issue[]): Pro
};
}
function printMarkdown(
function formatMarkdown(
changelog: Changelog,
issues: Issue[],
users: Issue["user"][],
@@ -266,12 +267,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 +285,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);
@@ -313,23 +317,37 @@ async function main() {
&& issue.pull_request.merged_at > lastRelease.created_at
));
const changelog = changelogFromPullRequests(pullRequests, issues);
const users = [...new Map(pullRequests.map(issue => [issue.user.login, issue.user])).values()]
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}`,
),
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();
for (const problem of notes.problems) {
console.warn(problem);
}
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) {
+103
View File
@@ -0,0 +1,103 @@
// Bumps the package versions, adds the release notes to CHANGELOG.md, then commits and tags the release.
// Usage: node scripts/prepare_release.mts [--force] <version>
// --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";
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 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] <version>, 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();
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);
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;
});
}
+35
View File
@@ -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/);
});
});
});