ci: adopt Changesets for versioning and publishing

[bmuenzenmeyer]

closes #791 - and a Slack thread

What

Replaces the bespoke package.json-diff publish flow with Changesets, so releases now produce a CHANGELOG.md, git tags, and GitHub Releases — none of which the previous process generated.

How it works now

• Contributors add a changeset per PR (node --run changeset) declaring the bump type + summary.
• When changesets land on main, changesets/action opens a "Version Packages" PR that bumps the version and writes CHANGELOG.md.
• Merging that PR publishes to npm (via the existing npm OIDC trusted publishing — no token), creates the v<x.y.z> git tag, and cuts a GitHub Release.

Changes

• package.json — add @changesets/cli + @changesets/changelog-github; add changeset, changeset:version, release scripts.
• .changeset/ — config (changelog-github, access: public, baseBranch: main), README, and one bootstrap changeset.
• .github/workflows/release.yml (new, replaces publish.yml) — changesets/action@v1.9.0 pinned by SHA; keeps harden-runner, npm OIDC, and the Slack notify. Permissions bumped to contents: write + pull-requests: write.
• CONTRIBUTING.md — "Adding a Changeset" and "Releasing" sections.

⚠️ Action required before first publish

The npm trusted-publisher config currently points at publish.yml. Since the workflow was renamed to release.yml, update the trusted publisher's workflow filename in the npm package settings, or the OIDC publish will fail.

Note

release.yml uses egress-policy: audit (not block) on harden-runner — the publish step legitimately reaches many endpoints (npm registry, sigstore provenance, GitHub API, git push, Slack) and a wrong block allowlist would hard-fail releases. The old publish job had no harden-runner at all, so this is still a net gain; it can be tightened to block once a real run reveals the exact endpoint list.

Verification

• changeset status validates config + sees the bootstrap changeset.
• A throwaway changeset version produced 1.4.1 + a clean CHANGELOG.md (reverted).
• lint + format:check pass.

🤖 Generated with Claude Code

[cursor]

PR Summary

Medium Risk
Changes how npm packages ship and requires updating npm trusted-publisher workflow name; misconfiguration could block releases until OIDC settings match release.yml.

Overview
Replaces the old publish.yml flow (publish when package.json version changes on main) with Changesets for versioning, changelog, tags, and GitHub Releases.

Adds .changeset/ config (GitHub changelog for nodejs/doc-kit, public access, main base branch) plus a bootstrap patch changeset. package.json gains @changesets/cli / @changesets/changelog-github and scripts changeset, changeset:version, and release (changeset publish).

New .github/workflows/release.yml runs changesets/action on every push to main: pending changesets open/update a Version Packages PR; after that merges, it publishes via npm OIDC, tags, and creates a GitHub Release. Keeps Slack notify on publish; adds harden-runner with audit egress (broader than the removed publish job’s blocked list). Job permissions include contents: write and pull-requests: write.

CONTRIBUTING.md documents contributor changesets and the maintainer release path (no manual version bumps).

Before the first publish: npm trusted publishing must reference release.yml instead of publish.yml.

^{Reviewed by Cursor Bugbot for commit 105d54d. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Jun 27, 2026 1:15pm

[codecov]

⚠️ JUnit XML file not found

The CLI was unable to find any JUnit XML files to upload.
For more help, visit our troubleshooting guide.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 105d54d. Configure here.}

[cursor]

Publish verification checks removed

Medium Severity

Replacing publish.yml drops the pre-publish checks that required a GPG-verified commit and a merge-queue committer before any npm publish. The new Release job runs changesets/action (including node --run release) on every push to main with no equivalent authenticity gate on the publish path.

 

^{Reviewed by Cursor Bugbot for commit 105d54d. Configure here.}