This document outlines the release process for the Nuxt UTM module.
We follow a PR-based release process that works with protected branches:
flowchart TD
A[Create release branch] --> B[Run pnpm release:prepare]
B --> C[Commit and push branch]
C --> D[Open PR to main]
D --> E[PR Review and Merge]
E --> F{GitHub Release exists?}
F -->|No| G[Create GitHub Release and tag on the release commit]
F -->|Yes| H[Skip GitHub Release]
E --> I{Version on npm?}
I -->|No| J[Build the release commit and publish to npm]
I -->|Yes| K[Skip publish]
-
Create a Release PR:
- Version bump in
package.json - CHANGELOG update
- Open PR for review
- Version bump in
-
Automated Release (GitHub Actions):
- Triggered automatically when the PR is merged to main
- Detects the new version and creates a git tag
- Creates a GitHub Release
- Publishes the package to npm through trusted publishing
-
Ensure you have the latest changes from the main branch:
git checkout main git pull origin main
-
Create a release branch:
git checkout -b release-X.Y.Z
-
Make sure all tests pass:
pnpm test -
Run the release script, which will:
- Bump the version in
package.json - Update the
CHANGELOG.md - Commit both as
chore(release): vX.Y.Z
pnpm release:prepare
The script leaves the tag and the GitHub Release to the merge workflow, which creates them on the merge commit. A tag pushed before the merge would point at the release branch, and the workflow stops instead of releasing from it.
changelogen lists each commit by its title. When the release changes behavior that consumers may need to act on, such as which visits count as campaigns or which fields an entry stores, add a short note to the new
CHANGELOG.mdsection and amend the release commit before pushing. - Bump the version in
-
Push the release branch:
git push -u origin release-X.Y.Z
-
Open a Pull Request to
mainand get it reviewed. -
Once the PR is merged, the CI will automatically:
- Detect the new version
- Create a git tag (
vX.Y.Z) - Create a GitHub Release
- Publish the package to npm
The release-on-merge.yml workflow runs on every push to main that modifies package.json, and can also be run manually from main. Runs wait for each other instead of overlapping. Each run:
- Reads the version from
package.jsonand finds its release commit: the commit onmainthat set that version, or the commit itsvX.Y.Ztag points at. The run stops if that tag is outsidemainor declares another version - Creates the GitHub Release on the release commit if it is missing, along with the tag when the tag does not exist yet
- Builds the release commit and publishes it to npm if npm does not have that version yet
Because every run releases the release commit rather than the latest commit on main, running the workflow again completes a missing GitHub Release or npm publish without picking up later changes. It only handles the version currently in package.json, so an older version left unfinished after the next version bump has to be completed outside the workflow.
The workflow publishes through npm trusted publishing and needs no npm token. npm exchanges the workflow's GitHub OIDC token for a short-lived publish token and generates provenance for the release. Only the publish job can request that OIDC token, and it publishes the tarball an earlier job built, so dependency install and build scripts never run with publish access.
This relies on a trusted publisher configured for the nuxt-utm package on npmjs.com:
- Provider: GitHub Actions
- Repository:
stackbuilders/nuxt-utm - Workflow filename:
release-on-merge.yml - Environment: none
A package maintainer can set it under the package's Settings on npmjs.com, or with npm 11.15 or later:
npm trust github nuxt-utm --repo stackbuilders/nuxt-utm --file release-on-merge.yml --allow-publishRenaming the workflow file requires updating this configuration.
We follow Semantic Versioning for this project:
- MAJOR version for incompatible API changes
- MINOR version for backwards-compatible functionality additions
- PATCH version for backwards-compatible bug fixes
If the automated release fails:
- Check the GitHub Actions logs for errors
- If publishing fails with
ENEEDAUTH,E401, orE404, confirm that the trusted publisher on npmjs.com namesstackbuilders/nuxt-utmandrelease-on-merge.ymlexactly. npm only validates that configuration when a publish runs - If the run stops because the tag must point at a commit on
mainthat sets the version, the tag was created outside the workflow. Delete the tag or move it to the release commit, then run the workflow again - Re-run the failed jobs, or run the Release on Merge workflow manually from
mainwhen the fix needed a change onmain. Both release the same commit and skip whatever already exists
If a release was skipped:
- The workflow only runs automatically when
package.jsonis modified onmain - Run the Release on Merge workflow manually from
mainto release the current version
- The release process uses changelogen to generate CHANGELOG entries
- Always verify that the published package works correctly by installing it in a test project
- The main branch is protected; all releases must go through a PR
For questions or assistance with the release process, please contact the maintainers or email community@stackbuilders.com.