Releasing

How versions, changelogs, and releases ship: changesets, the release workflow, provenance, and versioned docs.

@vortex-api/convex-auth releases are driven by changesets and GitHub Releases. The compatibility contract lives in VERSIONING.md; this page is the operator runbook.

Normal release flow

1. Every PR that changes packages/ source carries a changeset — enforced by the changeset-gate CI check. A PR can opt out only with the no-release label. Major-bump changesets must include a Migration note: line.
2. Merge to main. Changesets accumulate.
3. Run the Release workflow (workflow_dispatch). changesets/action opens a chore: version packages PR that bumps versions, consumes pending changesets, and prepends their entries to packages/auth/CHANGELOG.md. The changelog file is committed and load-bearing — changesets/action reads it at publish time to build the GitHub Release body, and silently skips the release if it is missing.
4. Merge the version PR, then re-dispatch the workflow. The publish run pushes npm, creates the git tag, and creates the GitHub Release via the GITHUB_TOKEN. Tags are @vortex-api/convex-auth@X.Y.Z (the changesets workspace format), immutable, and never moved.
5. The docs changelog updates itself — the Blume site sources changelog/* pages from GitHub Releases, so release notes appear on the docs site (with RSS) on the next site build/deploy. No hand-editing.

Supply chain

• npm publishes run with NPM_CONFIG_PROVENANCE=true, producing sigstore provenance attestations that link each tarball to this repo’s release run.
• GitHub Releases are created by the release workflow via GITHUB_TOKEN, so tags and release commits are GitHub-verified.

Major releases

A major additionally requires:

1. A Migration note: line in the changeset (gate-enforced).
2. A migration page under docs/(migrations)/ linked from the release notes.
3. After release, freeze the previous major’s docs: blume version v<N> in site/ — the old line stays reachable while latest moves forward.
4. If the HTTP contract changed, the openapi/auth.yaml diff must already be merged — the OpenAPI contract guard CI check fails any PR where code routes and spec paths diverge.

What the gates check