Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
77 lines (56 loc) · 2.49 KB

CONTRIBUTING.md

File metadata and controls

77 lines (56 loc) · 2.49 KB
Raw

Contributing

Development

Install dependencies and run the checks before opening a pull request:

pnpm install --frozen-lockfile
pnpm test -- --runInBand
pnpm build

Release configuration

Releases are handled by the release workflow. The workflow runs when a tag whose name starts with v is pushed. The tag version must exactly match the version in package.json.

Configure an Actions secret named NPM_TOKEN before the first release:

  1. Open the repository's Settings > Secrets and variables > Actions page.
  2. Add a repository secret named NPM_TOKEN with an npm access token that can publish this package.
  3. Optionally create a GitHub Environment named npm and configure required reviewers for releases.

GITHUB_TOKEN, GITHUB_REF_NAME, and the npm registry URL are provided by GitHub Actions and do not need to be configured manually.

Publishing a release

Start from an up-to-date branch with a clean working tree. Create the version commit and tag, then push both:

git switch main
git pull --ff-only
pnpm install --frozen-lockfile
pnpm test -- --runInBand
pnpm build
npm version patch
git push --follow-tags origin main

Use npm version minor or npm version major when appropriate. The workflow validates the version, installs dependencies, runs tests, builds all distributions, checks the package contents, publishes to npm with provenance, and creates a GitHub Release.

Prerelease versions such as 1.9.0-beta.0 are automatically published with the npm next dist-tag:

npm version prerelease --preid=beta
git push --follow-tags origin main

Retrying a failed release

For transient infrastructure failures, use Re-run jobs from the failed workflow run. A rerun always uses the workflow and source from the commit referenced by the existing tag.

If the workflow itself had to be fixed, rerunning the old job will not use that fix. The safest option is to publish a new patch version after merging the workflow change:

npm version patch
git push --follow-tags origin main

If the failure happened before npm publishing and no GitHub Release was created, the original tag may instead be recreated on the fixed commit. Verify both conditions before doing this:

git tag -d v1.8.0
git push origin :refs/tags/v1.8.0
git tag v1.8.0
git push origin HEAD
git push origin v1.8.0

Never move or reuse a tag after that version has been published to npm. npm package versions are immutable; create a new patch version instead.