Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 48 additions & 0 deletions .github/RELEASING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# Releasing

Maintainers choose the release version in a pull request. Commit messages do not
trigger automatic version bumps or npm releases.

1. Create a branch from `master`.
2. Update `package.json` with `npm version patch --no-git-tag-version`, or choose
the required minor, major, or explicit version.
3. Add the release notes to `CHANGELOG.md` and open a PR into `master`.
4. Merge the PR after its CI checks pass.

The `Release` workflow compares the package versions before and after the push
to `master` and publishes when the version changes. Dependency-only changes do
not publish a package. The workflow does not check whether the push came from a
PR; branch protection can enforce that repository policy.
Comment thread
fengmk2 marked this conversation as resolved.
Resolved

The workflow checks out the exact pushed commit and installs dependencies.
`npm publish` runs the `prepublishOnly` script to build the package. The release
workflow relies on the PR's CI checks and does not run them again. It publishes
stable versions with the `latest` npm tag and prerelease versions with `next`.
It then creates a `v<version>` tag and a GitHub release with generated notes.
Release jobs run one at a time, with up to 100 pending jobs queued.

Stable releases use npm's default `latest` tag without an explicit `--tag` option.
If a newer stable version is already published, npm rejects an older unpublished
version instead of moving `latest` backward. This also applies when retrying an
older release job.

If a release fails, rerun its failed jobs in GitHub Actions. The workflow skips
versions that already exist on npm and GitHub releases that already exist, so a
retry can finish creating the GitHub release without publishing the package again.

## npm trusted publisher

Configure the `utility` package's trusted publisher on npm with:

- Organization: `node-modules`
- Repository: `utility`
- Workflow filename: `release.yml`
- Environment: leave empty
- Allowed action: `npm publish`

The workflow uses Node.js 24, npm 11, and `id-token: write` for OIDC authentication.
It does not use an npm token or the `GIT_TOKEN` secret. GitHub release creation
uses the repository's built-in `GITHUB_TOKEN`.

See the [npm trusted publishing documentation](https://docs.npmjs.com/trusted-publishers/)
for the package settings.
127 changes: 122 additions & 5 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,127 @@ name: Release
on:
push:
branches: [ master ]
paths: [ package.json ]

permissions:
contents: read

jobs:
release:
name: NPM
uses: node-modules/github-actions/.github/workflows/npm-release.yml@master
secrets:
GIT_TOKEN: ${{ secrets.GIT_TOKEN }}
version:
name: Check version change
runs-on: ubuntu-latest
outputs:
changed: ${{ steps.version.outputs.changed }}
version: ${{ steps.version.outputs.version }}
npm_tag: ${{ steps.version.outputs.npm_tag }}
steps:
- uses: actions/checkout@v7
with:
fetch-depth: 0
persist-credentials: false

- name: Compare package versions
id: version
uses: actions/github-script@v9
with:
script: |
const { execFileSync } = require('node:child_process');
const readPackage = ref => JSON.parse(execFileSync(
'git', ['show', `${ref}:package.json`], { encoding: 'utf8' }
));
const previous = readPackage(context.payload.before);
const current = readPackage(context.sha);
if (previous.version === current.version) {
core.info('The package version did not change.');
return;
}
if (current.name !== previous.name || typeof current.version !== 'string') {
throw new Error('The release must keep the package name and specify a version.');
}
core.setOutput('changed', 'true');
core.setOutput('version', current.version);
core.setOutput('npm_tag', current.version.includes('-') ? 'next' : 'latest');

publish:
name: Publish to npm
needs: version
if: needs.version.outputs.changed == 'true'
runs-on: ubuntu-latest
permissions:
contents: write
id-token: write
concurrency:
group: npm-release
cancel-in-progress: false
Comment thread
fengmk2 marked this conversation as resolved.
Resolved
queue: max
env:
RELEASE_VERSION: ${{ needs.version.outputs.version }}
NPM_TAG: ${{ needs.version.outputs.npm_tag }}
steps:
- uses: actions/checkout@v7
with:
ref: ${{ github.sha }}
persist-credentials: false

- uses: actions/setup-node@v7
with:
node-version: '24'
registry-url: https://registry.npmjs.org
package-manager-cache: false

- name: Use npm with trusted publishing support
run: npm install --global npm@11

- name: Check whether the version is already published
id: npm
uses: actions/github-script@v9
with:
script: |
const { readFileSync } = require('node:fs');
const { name, version } = JSON.parse(readFileSync('package.json', 'utf8'));
const response = await fetch(
`https://registry.npmjs.org/${encodeURIComponent(name)}/${encodeURIComponent(version)}`
);
if (response.status === 404) {
core.setOutput('published', 'false');
} else if (response.ok) {
core.info(`${name}@${version} is already published.`);
core.setOutput('published', 'true');
} else {
throw new Error(`npm registry check failed: ${response.status}`);
}

- name: Install dependencies
if: steps.npm.outputs.published == 'false'
run: npm install --no-package-lock --no-fund

- name: Publish with npm trusted publishing
if: steps.npm.outputs.published == 'false'
run: |
if [[ "$NPM_TAG" == "next" ]]; then
npm publish --provenance --access public --tag next
else
# Keep npm's implicit-latest guard against publishing an older version.
npm publish --provenance --access public
fi

- name: Create GitHub release
uses: actions/github-script@v9
with:
script: |
const tag = `v${process.env.RELEASE_VERSION}`;
try {
await github.rest.repos.getReleaseByTag({ ...context.repo, tag });
core.info(`${tag} already has a GitHub release.`);
return;
} catch (error) {
if (error.status !== 404) throw error;
}
await github.rest.repos.createRelease({
...context.repo,
tag_name: tag,
target_commitish: context.sha,
name: tag,
generate_release_notes: true,
prerelease: process.env.NPM_TAG === 'next',
});
5 changes: 5 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -359,6 +359,11 @@ new Date().toString() x 816,731 ops/sec ±3.46% (93 runs sampled)
Fastest is utils.datestruct().YYYYMMDD
```

## Releasing

See the [release guide](.github/RELEASING.md) for the version PR and npm trusted
publishing process.

## License

[MIT](LICENSE.txt)
Expand Down
Loading