Skip to content

Commit b62637e

Browse files
committed
docs: clarify release approval flow
1 parent 86944f4 commit b62637e

1 file changed

Lines changed: 11 additions & 6 deletions

File tree

CONTRIBUTING.md

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -188,19 +188,24 @@ We closely watch our issues and have a pretty active [Slack workspace](https://c
188188
This guide is intended for core team members that have the necessary
189189
rights to publish new releases on npm.
190190

191-
Before using the automated npm publishing flow, make sure npm trusted publishing is configured for the `preactjs/preact` repository, the `release.yml` workflow, and the `npm` environment. The GitHub `npm` environment should require reviewer approval, and repository rules should protect `11.*` tags.
191+
Before using the automated npm publishing flow, make sure npm trusted publishing is configured for the `preactjs/preact` repository, the `release.yml` workflow, and the `npm` environment. The trusted publisher must allow `npm stage publish`. The GitHub `npm` environment should require reviewer approval, and repository rules should protect `11.*` tags.
192192

193193
1. Make a PR where **only** the version number is incremented in `package.json` and everywhere else. A simple search and replace works. (note: We follow `SemVer` conventions)
194194
2. Wait until the PR is approved and merged.
195195
3. Switch back to the `main` branch and pull the merged PR
196196
4. Create and push a tag for the new version you want to publish:
197197
1. `git tag 11.0.0`
198198
2. `git push origin 11.0.0`
199-
5. Wait for the Release workflow to reach the `npm` environment approval gate, approve it, and let it complete
200-
- It'll validate that the tag matches the package version, create a draft release, upload the built npm package as a release asset, and publish it to npm.
201-
- Stable releases publish to the `latest` npm dist-tag; prereleases publish to the approved prerelease dist-tag (`alpha`, `beta`, `rc`, or `next`).
202-
6. [Fill in the release notes](#writing-release-notes) in GitHub and publish them
203-
7. Tweet it out
199+
5. Open the tag's **Release** workflow in GitHub Actions and wait for the `publish` job to request approval for the `npm` environment.
200+
- Before this gate, the workflow builds and tests the tag, creates a draft GitHub release, and uploads the exact npm tarball as a release asset.
201+
- Review the workflow, tag, commit, and tarball. Then approve the deployment to the `npm` environment.
202+
- The `publish` job validates that the package name and version match the tag, selects the npm dist-tag, and submits the tarball with `npm stage publish`. A successful job means the package is staged; it is **not public yet**.
203+
6. Open the **Staged Packages** tab on npmjs.com and review the staged `preact` package.
204+
- Stable releases use the `latest` npm dist-tag; prereleases use the approved prerelease dist-tag (`alpha`, `beta`, `rc`, or `next`).
205+
- Approve the staged package and complete the 2FA challenge. This is the step that publishes it to the live npm registry.
206+
- Verify the new version and expected dist-tag with `npm view preact@11.0.0 version dist-tags --json`.
207+
7. [Fill in the release notes](#writing-release-notes) in GitHub and publish them
208+
8. Tweet it out
204209

205210
## Legacy Releases (8.x)
206211

0 commit comments

Comments
 (0)