Skip to content

Releasing

github-actions[bot] edited this page Nov 21, 2026 · 1 revision

Releasing

Spotstrap follows SemVer. Its public API is the export paths, the token names, the theme names, and the blocks' exports and document shape (ADR 0010): renaming or removing any of them is a breaking change. While the version is 0.y.z, a breaking change raises the minor version.

A release

  1. On a chore/release-0.2.0 branch from origin/main, set version in package.json, and in CHANGELOG.md rename Unreleased to the version and date and add its compare link. Open a pull request into main and merge it once the checks pass.
  2. Tag the merge commit and push the tag: git fetch origin && git tag -s v0.2.0 'origin/main^{commit}' -m v0.2.0 && git push origin v0.2.0. There is no other branch to merge back into (ADR 0009).
  3. CI verifies the tagged commit, then publishes @kodentuzo/spotstrap to npm (latest, or next for a pre-release) with provenance. A version already on npm is skipped, so a failed run can be re-run.
  4. Publish a GitHub Release for the tag with its changelog section.
  5. The package carries the registry (dist/registry/). To serve a new version's registry and themes on kodentuzo.com, update @kodentuzo/spotstrap in kodentuzo/website and release it.

An npm version can't be replaced: fix a broken one with a new patch release and deprecate the broken one (npm deprecate @kodentuzo/spotstrap@0.1.0 "Use 0.1.1").

One-time npm setup

Only the original repository (kodentuzo/spotstrap) publishes; CI skips the step in forks.

  1. First release only: npm can't link a trusted publisher to a package that doesn't exist yet, so the first version needs a token:
    • on npmjs.com, the free organization kodentuzo owns the @kodentuzo scope;
    • create a granular access token that can publish packages, with read and write on the kodentuzo organization and 2FA bypass (expiry: a few days);
    • store it as the secret NPM_TOKEN in a GitHub environment named npm in kodentuzo/spotstrap;
    • release as above.
  2. On npmjs.com, in the settings of @kodentuzo/spotstrap, link a trusted publisher. The fields are case-sensitive:
    • provider: GitHub Actions;
    • organization or user: kodentuzo, repository: spotstrap;
    • workflow filename: ci.yml, environment: npm;
    • allow npm publish.
  3. Delete the NPM_TOKEN secret and revoke the token. From then on CI publishes through GitHub's OIDC token, with no stored secret.

Clone this wiki locally