Skip to content

RELEASING.md

Latest commit

 

History

History
88 lines (69 loc) · 3.55 KB

RELEASING.md

File metadata and controls

88 lines (69 loc) · 3.55 KB
Raw

Releasing wouter

The Publish packages workflow publishes wouter and wouter-preact together. It runs tests with coverage, type checks, lint, size checks, and package-content checks before publishing the exact tarballs it inspected. Stable versions use latest; prereleases use next. Every run, including dry runs, waits for manual approval before the publish job starts.

GitHub approval setup

The publish job uses the npm GitHub environment. In the repository's environment settings, require molefrog as a reviewer and disable administrator bypass. Allow self-review so the maintainer can approve releases they initiate.

One-time npm setup

Merge .github/workflows/release.yml into main. In the npm settings for each package, add a GitHub Actions trusted publisher:

Setting Value
Organization or user molefrog
Repository wouter
Workflow filename release.yml
Environment name npm
Allowed actions Enable direct publishing with npm publish

Configure both wouter and wouter-preact. No NPM_TOKEN secret is needed. npm uses GitHub OIDC and attaches provenance automatically. See npm's trusted publishing guide. Restrict both trusted publishers to the npm environment so older workflow revisions without the approval gate cannot authorize publishing.

Publish a version

  1. Set the same new version in packages/wouter/package.json and packages/wouter-preact/package.json. Run bun install --lockfile-only to update bun.lock, then commit and merge the version change into main.

  2. Tag that commit and push the tag (replace the example version):

    git switch main
git pull --ff-only
git tag v3.12.0
git push origin v3.12.0

The tag push starts a workflow that waits for approval. Open the Actions run, choose Review deployments, select npm, then Approve and deploy to continue. A tag such as v3.12.0-next.0 publishes both packages under next without changing latest. The tag must match both package versions and point to a commit on main. Build metadata (+...) is not supported in release tags.

To publish an existing tag manually, choose Publish packages → Run workflow, leave the workflow branch as main, and enter the tag. Or use:

gh workflow run release.yml --ref main -f tag=v3.12.0

Select Validate and pack without publishing (or add -F dry_run=true) to check an existing tag without publishing. Dry runs also require approval; a tag push publishes after approval.

Verify or retry

Check the Actions run, then inspect both packages:

npm view wouter@3.12.0 version dist.attestations
npm view wouter-preact@3.12.0 version dist.attestations
npm view wouter dist-tags
npm view wouter-preact dist-tags

npm cannot publish two packages atomically. If one succeeds and the other fails, fix the reported issue and rerun the same tag. Existing versions are skipped; their dist-tags are left unchanged. Registry errors other than a missing version stop the run. Never move a released tag or try to overwrite a published version; code changes require a new version.

For tags created before the approval gate was added, start a new manual run from main with the existing tag. Rerunning an old Actions run uses its original workflow revision and does not add the gate.