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/); + }); + }); +});