diff --git a/.github/RELEASING.md b/.github/RELEASING.md new file mode 100644 index 0000000..b948bf0 --- /dev/null +++ b/.github/RELEASING.md @@ -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. + +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` 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. diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index b8d6a72..a34adc7 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -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 + 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', + }); diff --git a/README.md b/README.md index 4d3c8ef..ce101c7 100644 --- a/README.md +++ b/README.md @@ -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)