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 releases run and grants the workflow write access for version PRs, tags, and releases; first publish fails until npm trusted-publisher workflow filename is updated.

Overview
Replaces the old publish pipeline with Changesets: contributors add .changeset/ entries per PR, and CI opens a Version Packages PR or publishes when those are consumed.

• Removes .github/workflows/publish.yml (trigger on package.json changes, GPG/merge-queue checks, direct npm publish).
• Adds .github/workflows/release.yml using changesets/action with changeset:version / release scripts, fork guard, release concurrency, harden-runner (egress-policy: audit), and Slack notify when published == 'true'. Job permissions rise to contents: write and pull-requests: write for version PRs, tags, and GitHub Releases.
• Adds .changeset/config.json (GitHub changelog for nodejs/doc-kit), docs README, and a bootstrap patch changeset for adopting Changesets.
• Updates CONTRIBUTING.md with Adding a Changeset and Releasing (no hand-editing package.json version).

Ops note: npm trusted publishing must point at release.yml instead of publish.yml or OIDC publish will fail.

^{Reviewed by Cursor Bugbot for commit 35c6401. 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	Jul 5, 2026 1:19am

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.00%. Comparing base (9c5f11f) to head (35c6401).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #855   +/-   ##
=======================================
  Coverage   85.00%   85.00%           
=======================================
  Files         179      179           
  Lines       16453    16453           
  Branches     1491     1491           
=======================================
  Hits        13986    13986           
  Misses       2457     2457           
  Partials       10       10           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[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.}