Releases are built on GitHub Actions and staged on npm. A staged version is only published after it has been reviewed and approved with 2FA. Do the review and approval on a trusted device, such as your phone, not on the machine that pushed the tag.
- Add a
## x.y.zentry to CHANGELOG.md. - Bump the version:
npm version x.y.z --no-git-tag-version - Commit both and push to master.
- Wait for the Node.js CI and Integration Tests runs for that commit to pass.
- Tag and push:
git tag vx.y.z && git push origin vx.y.z
Never run npm publish or npm stage publish locally, and stay logged out of npm on this machine (npm logout). A version without provenance is not ours.
The Stage release workflow runs on the tag. It:
- checks that the tag matches package.json, the commit is on master and the changelog has an entry
- runs lint, build and unit tests
- stages the version on npm with
npm stage publish - creates a draft GitHub release with the changelog entry
- Open the workflow run in the Actions tab. Note the commit SHA in the run's header and check that the "Run npm stage publish" step succeeded.
- Check that the Node.js CI and Integration Tests runs on master passed for that SHA.
- Check the compare link in the run summary. It must start with the previous release tag and end with the SHA from the header. Don't rely on the summary alone, since the workflow itself writes it. Alternatively, type the link yourself:
https://github.com/patrickjuchli/basic-ftp/compare/v<previous>...<sha> - Open the compare link and review every changed file, not just
src/. Expand collapsed diffs.- Code that runs during the build: test files,
eslint.config.mjsandtsconfig.json. Tests run after the build and could changedist/before it's staged. - package-lock.json: every version change is one you made, and every
resolvedURL points tohttps://registry.npmjs.org/. - .github/: no unexpected changes to workflows or scripts.
- package.json: no new scripts, dependencies or changes to
files. - Commits: no commits you don't recognize.
- Code that runs during the build: test files,
- On npmjs.com under "Staged Packages" in the user menu at the top right, the version must match the tag and be the only staged entry.
- Optional:
npm stage download <stage-id>to inspect the staged tarball.
If anything is unexpected, reject all staged versions on npm and investigate before doing anything else.
- Approve the staged version under "Staged Packages", with 2FA.
- Check that the version's page on npmjs.com shows provenance with the commit SHA you reviewed.
- Publish the draft release on GitHub.
- Checks or tests failed: nothing was staged. Fix it, move the tag and push again:
git tag -f vx.y.z && git push -f origin vx.y.z - Staged, but the draft release failed: re-run the failed job in the Actions tab.
- Staged, but must not be published: reject it on npm and release the fix as the next version.