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>
4.6 KiB
Release workflow
Update changelog
- CHANGELOG.md in the repository root
- The changelog.txt file 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.
Packages
The Publish workflow publishes npm packages and Lua mods on GitHub's release: released event for a stable release.
Publishing a prerelease does not trigger it; see GitHub's release event documentation.
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, 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, 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
You will need commit access to the repository as well publish access to the @clusterio org on npm to do this.
-
Inspect
git statusandgit remote -v, verify which remote is the main repository, and use a clean release worktree on its latest master. The commands below assume that remote is namedupstream; preserve unrelated work and external plugin checkouts.git switch master git pull --ff-only upstream master git status -
Run the prepare release script with the new version. It sets the version in the
package.jsonfiles underpackages/andplugins/, adds the changelog from merged pull requests to the top of CHANGELOG.md, commits it as "Prepare 2.0.2" and tags that commitv2.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--forceto continue anyway. Entries with warnings are kept, pull requests whose changelog section could not be read are left out.node scripts/prepare_release.mts 2.0.2 -
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.git show HEAD git push upstream master v2.0.2 -
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.node scripts/clean.js --dry-run pnpm clean pnpm install --no-frozen-lockfile pnpm -r --filter='./packages/*' --filter='./plugins/*' --fail-if-no-match publish
Plugins
- Bump the version in the
package.jsonfile - Run
pnpm install --no-frozen-lockfilein the repository root - Run
pnpm adduserto authenticate - Run
pnpm publishin the plugin/package directory
Before confirming the publish, ensure the packed size is approximately the same size as the last version (or within the expected size)
After publishing, test creating and installing the plugin on a fresh install.
Lua mods
To publish lua mods like clusterio_lib, start by building from source:
pnpm run build-mod
or download the latest artifacts from the CI. When uploading the mods to the mod portal, make sure the latest version is the last version uploaded, as the game/mod portal/ingame updater isn't consistent in how it figures out the "latest version"
Release notes
Release notes are expected to be published alongside new releases. We use the github releases system as well as posting in the #announcements channel on the discord. Major releases may warrant a ping.