Versioning & releases

dsp-audio-metrics follows semantic versioning. The public surface that counts is the src/index.d.mts type declarations: a breaking change to any exported function signature bumps the major version.

The release gate

Releases are driven entirely by git tags, and enforced by script/check-release.mjs (unit-tested, 100% line coverage) plus the publish.yml workflow:

1. Tag — push a vX.Y.Z tag.
2. Check — check-release.mjs verifies the tag parses, exactly matches package.json's version, and is a single-step, coherent bump from the latest existing tag (v0.1.0 → v0.1.1 OK, v0.1.0 → v0.2.0 OK, v0.1.0 → v0.3.0 rejected, downgrades rejected).
3. Test — the matrix runs npm test on Node 18 / 20 / 22, and the coverage gate (--test-coverage-lines=95 --test-coverage-branches=90 --test-coverage-functions=95) on Node 22.
4. Publish — npm publish --provenance runs only on the tag that passed.

This is the same design as the drizzle-migrate-neon-http package, which this project mirrors.

Versioning the docs

The docs live on a separate docs branch (VitePress) and deploy to GitHub Pages on every push to that branch. API docs are written by hand against src/index.d.mts and reviewed in the same PR that changes the types, so the docs branch is always in sync with the latest main.

Procedure

# feature work on main
git checkout main
npm version patch   # or minor / major — bumps version + creates the tag
git push --follow-tags

GitHub Actions does the rest. If the gate rejects the bump (e.g. you skipped a version), delete the tag and npm version again: