Skip to content

RELEASING.md

Latest commit

 

History

History
71 lines (46 loc) · 5.13 KB

RELEASING.md

File metadata and controls

71 lines (46 loc) · 5.13 KB

Releases & dependency updates

This repo uses Dependabot for dependency PRs and semantic-release on the default branch (master) to publish to npm and maintain CHANGELOG.md.

One-time setup (GitHub + npm)

  1. Branch
    Releases are configured for master, which matches the current GitHub default. If you rename the default branch to main, update branches in both .github/workflows/release.yml and .releaserc.json to main.

  2. npm Trusted publishing (recommended)
    Publishes from CI use Trusted publishing (OpenID Connect) so you do not store a long-lived NPM_TOKEN in GitHub. Requirements are described in the npm docs (Node ≥ 22.14.0 and npm CLI ≥ 11.5.1); this repo’s workflow uses Node 22.14 on GitHub-hosted ubuntu-latest.

    On npmjs.com (package → Settings → Trusted publishing):

    • Publisher: GitHub Actions
    • Organization or user: match the GitHub owner (e.g. cdeutsch for github.com/cdeutsch/classy-forms)
    • Repository: classy-forms
    • Workflow filename: release.yml (filename only, including .yml, must match .github/workflows/release.yml exactly)
    • Environment name: leave empty unless you intentionally use a GitHub Environment named in npm; if you set one on npm, configure the same on the workflow job.

    On GitHub: the workflow already declares id-token: write (required for OIDC). No NPM_TOKEN secret is used.

    After a successful release via this workflow, you can remove any old automation tokens and optionally tighten package Publishing access so publishes go through Trusted publishing only.

    Fallback (unsupported CI only): If you ever publish from a context where Trusted publishing is unavailable, use a short-lived granular access token and set NPM_TOKEN for that job only — not the default for this repo.

  3. GITHUB_TOKEN
    Workflows use the built-in GITHUB_TOKEN. No secret is required for it. Ensure Settings → Actions → General allows workflow Read and write permissions (needed to push the release commit and create releases).

Continuous integration

The CI workflow runs npm test and npm run build on pull requests and on pushes to master, so regressions are caught before or at merge time.

How a release happens

  1. Push commits to master that follow Conventional Commits (e.g. fix: ..., feat: ...).
  2. The Release workflow runs tests and npm run build, then semantic-release (the build step stays here because dist/ is not committed and must exist for npm publish):
    • Decides the next semver from commits since the last release.
    • Updates package.json, CHANGELOG.md, and publishes to npm.
    • Creates a Git tag and GitHub Release.
  3. Release commits include [skip ci] in the message so the workflow does not run again on that push.

If there is no user-facing change that matches your configured rules (for example, only chore:/docs: with the default Angular preset), no new version is published and the workflow still exits successfully.

Commit types (default analyzer)

Commit type semver bump
fix: patch
feat: minor
BREAKING CHANGE: in footer or feat!: / fix!: / etc. major

Dependabot

Dependabot opens PRs monthly for npm (root and demo/) and GitHub Actions. PR titles use fix(deps):, which matches the default semantic-release analyzer for a patch bump only when that title survives as the final commit subject on master (for example via squash or rebase merge). GitHub’s default merge commit message (Merge pull request #…) does not follow Conventional Commits, so those merges usually do not produce a patch release from the PR title alone.

Local dry run (optional)

Use Node ^22.14.0 or ≥24.10.0 locally (same range as semantic-release 25 and Trusted publishing). Older 22.x patch levels may show EBADENGINE warnings from npm even though install succeeds.

npm ci
git fetch origin
npx semantic-release --dry-run

No publish or git writes occur; useful to see the next version and notes. The configured release branch (master) must exist on origin or the dry run exits with ERELEASEBRANCHES.

Replacing manual npm publish

Do not run npm publish by hand for normal releases. Let the workflow publish so versions, tags, and CHANGELOG.md stay aligned. For emergencies only, document the manual steps in an issue and coordinate with npm.