ci: semantic releases

[dhensby]

Summary

This change adds semantic releases to the release pipeline. Commits are automatically analysed when they are merged into master and depending on the commit message (fix, feat), a new release will be authored (tagged in git, pushed to GH releases and NPM); this includes updating the release version in package.json and updating the CHANGELOG.MD.

Other added benefits are NPM attestation of releases, no human dependencies on releases, fixes are released as soon as they are merged.

Contributors will now have to ensure their commits conform to the conventional commits standard

Outstanding actions:

1. Someone with publish permissions to the NPM repository will need to create a fine-grained access token to allow publishing of the package - this must then be added to the github repo secrets with the name NPM_TOKEN.
2. Someone with admin rights to the GH repo will need to create a fine-grained access token to allow pushing to the repository - this must then be added to the github repo secrets with the name GITHUB_TOKEN.

There is now no longer a need for an NPM_TOKEN to. be stored as a secret as NPM supports trusted publishing and uses federated credentials for publishing instead.

The GH token needs the following access:

      contents: write # to be able to publish a GitHub release & commit changelog changes
      issues: write # to be able to comment on released issues
      pull-requests: write # to be able to comment on released pull requests
      id-token: write # to enable use of OIDC for npm provenance

Linked issue(s)

See discussion #310

Involved parts of the project

Releases / automation.

Added tests?

N/A

OAuth2 standard

N/A

Reproduction

N/A

[jankapunkt]

Thanks a lot for this @dhensby

I have nom publishing access but I'd like to limit this only to the master branch so new releases are definitely reviewed beforehand by at least two of us. What do you think?

[dhensby]

By default the release process won't work unless it's in a list of the default branches (master, next, and then N.x for changes to other versions). We can limit this to just master either in the release config or in the GH workflow (or both).

[jankapunkt]

Ok then we can leverage npm tags so everything on next is also tagged @next (like alpha beta release candidate) and not auto installed by users while releases on master can be tagged @latest so they are installable without explicit version pinning

[dhensby]

Yep - that's how it works "out of the box" 👍

[jankapunkt]

@dhensby I just merged some dependabot dev-dependencies. Would these kinds of merges be ignored by your current PR?

[dhensby]

I just merged some dependabot dev-dependencies. Would these kinds of merges be ignored by your current PR?

No; they are flagged as build: or sometimes chore(deps): commits that don't trigger releases. Also, if you use @dependabot merge command, the CI is run in reduced-privilege mode which means that the runs don't have access to the secrets and so they can't be used to perform releases.

In regard to dependencies, our version constraints should be permissive enough that any upstream consumer can be responsible for upgrading any packages that have vulnerabilities or bugs; if we start to depend on new major versions of dependencies that form part of our outward facing APIs (I don't think they do), then we should probably manually update them with at least minor and maybe major change releases.

[Copilot]

Pull request overview

This PR introduces automated semantic-versioned releases using semantic-release, along with commit message linting to enforce Conventional Commits as part of the CI pipeline.

Changes:

• Add semantic-release configuration (including changelog + git commit of release artifacts).
• Add commitlint configuration and CI steps to validate commit messages for pushes/PRs.
• Extend the existing CI workflow to include a release job and adjust lint scripts/changelog header to match the release tooling.

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
release.config.mjs	Defines semantic-release plugins and release/changelog/git behavior.
commitlint.config.mjs	Adds Conventional Commits lint rules for CI enforcement.
package.json	Adds devDependencies for commitlint/semantic-release tooling and updates lint scripts.
CHANGELOG.md	Updates heading to match semantic-release changelog plugin title.
.github/workflows/tests.yml	Adds commitlint checks, fetch-depth changes, and a semantic-release publish job.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[dhensby]

Addressed the review comments (as fixup! commits, ready to autosquash):

1. release.config.mjs preset — moved preset: 'conventionalcommits' onto @semantic-release/commit-analyzer and @semantic-release/release-notes-generator (it's not a recognized core option at the top level, so the plugins were silently defaulting). The preset itself resolves via semantic-release's bundled conventional-changelog-conventionalcommits, so no extra dependency is needed.
2. commitlint on push — replaced --last with --from ${{ github.event.before }} --to ${{ github.sha }} so every commit in a push is validated, not just the tip. The lint job already checks out with fetch-depth: 0, and pushes are limited to master/development (so before is always a real SHA).
3. Action versions — bumped the release job's actions/checkout / actions/setup-node from @v4 to @v6 (and node 22 → 24) to match the other jobs.
4. Release token — GITHUB_TOKEN now uses ${{ secrets.RELEASE_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}, so a dedicated PAT can be supplied to push the release commit/tag to the protected master branch, falling back to the built-in token when it isn't set.

Re the branch discussion above: kept the semantic-release default branches (master → @latest, next/N.x → prerelease/@next tags), so master releases still go through PR review and next stays non-default-installable.