Files
factorio-clusterio/docs/release-workflow.md
T
bbassieandClaude Opus 5.5 3ca203c753 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>
2026-11-21 02:56:38 +00:00

91 lines
4.6 KiB
Markdown

# 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](../.github/workflows/publish.yml) 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](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, 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.
1. Inspect `git status` and `git 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 named `upstream`; preserve unrelated work and external plugin checkouts.
```sh
git switch master
git pull --ff-only upstream master
git status
```
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
node scripts/prepare_release.mts 2.0.2
```
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 show HEAD
git push upstream master v2.0.2
```
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.
```sh
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
1. Bump the version in the `package.json` file
2. Run `pnpm install --no-frozen-lockfile` in the repository root
3. Run `pnpm adduser` to authenticate
4. Run `pnpm publish` in 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:
```sh
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.