ci: adopt Changesets for versioning and publishing

.changeset/README.md

@@ -0,0 +1,9 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool
+that works with multi-package repos, or single-package repos to help you version and publish your
+code. You can find the full documentation for it
+[in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

.changeset/adopt-changesets.md

@@ -0,0 +1,6 @@
+---
+'@node-core/doc-kit': patch
+---
+
+Adopt Changesets for releases: versioning and publishing are now driven by changeset files, which
+produce a `CHANGELOG.md`, git tags, and GitHub Releases.

.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.4/schema.json",
+  "changelog": ["@changesets/changelog-github", { "repo": "nodejs/doc-kit" }],
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.github/workflows/release.yml

@@ -0,0 +1,82 @@
+name: Release
+
+# This workflow drives releases with Changesets.
+#
+# On every push to `main` it runs `changesets/action`, which behaves in one of two ways:
+#   * If there are pending changeset files, it opens/updates a "Version Packages" PR that bumps the
+#     version and writes CHANGELOG.md.
+#   * If there are no pending changesets (i.e. the "Version Packages" PR was just merged), it runs
+#     `changeset publish`, which publishes to npm (via npm OIDC trusted publishing), creates the git
+#     tag, and cuts a GitHub Release.
+
+on:
+  push:
+    # For security reasons, this should never be set to anything but `main`
+    branches: [main]
+
+permissions:
+  contents: read
+
+# Serialize releases. `cancel-in-progress: false` so a mid-publish run is never
+# killed by a newer push.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    # Never attempt to publish from forks (no trusted-publisher match / secrets).
+    if: github.repository == 'nodejs/doc-kit'
+    permissions:
+      contents: write # commit the version bump, push the git tag, create the GitHub Release
+      pull-requests: write # open/update the "Version Packages" PR
+      # For npm OIDC (https://docs.npmjs.com/trusted-publishers)
+      id-token: write
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
+        with:
+          # `audit` (not `block`) because the publish step reaches many endpoints (npm registry,
+          # sigstore provenance, the GitHub API, git push, Slack); a wrong allowlist would break a
+          # release. Egress is still recorded for review.
+          egress-policy: audit
+
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          # Changesets needs full history (and credentials) to push the version branch and tags.
+          fetch-depth: 0
+
+      - name: Setup environment
+        uses: nodejs/web-team/actions/setup-environment@9f3c83af227d721768d9dbb63009a47ed4f4282f
+        with:
+          use-version-file: true
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Create Release Pull Request or Publish
+        id: changesets
+        uses: changesets/action@a45c4d594aa4e2c509dc14a9f2b3b67ba3780d0d # v1.9.0
+        with:
+          version: node --run changeset:version
+          publish: node --run release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Notify
+        if: steps.changesets.outputs.published == 'true'
+        uses: rtCamp/action-slack-notify@33ca3be66c6f378fe1610fd1d5258632dbed5e58 # v2.4.0
+        env:
+          SLACK_COLOR: '#43853D'
+          SLACK_ICON: https://github.com/nodejs.png?size=48
+          SLACK_TITLE: ':rocket: Package Published: @node-core/doc-kit'
+          SLACK_MESSAGE: |
+            :package: *Package*: `@node-core/doc-kit` (<https://www.npmjs.com/package/@node-core/doc-kit|View on npm>)
+            :bust_in_silhouette: *Published by*: ${{ github.triggering_actor }}
+            :octocat: *Commit*: <https://github.com/${{ github.repository }}/commit/${{ github.sha }}|${{ github.sha }}>
+          SLACK_USERNAME: nodejs-bot
+          SLACK_CHANNEL: nodejs-web-infra-alerts
+          SLACK_TOKEN: ${{ secrets.SLACK_TOKEN }}

CONTRIBUTING.md

@@ -10,6 +10,7 @@ Thank you for your interest in contributing to the `@node-core/doc-kit` project!
   - [Running the Tool Locally](#running-the-tool-locally)
 - [Development Workflow](#development-workflow)
   - [Making Changes](#making-changes)
+  - [Adding a Changeset](#adding-a-changeset)
   - [Submitting Your Changes](#submitting-your-changes)
 - [Writing Tests](#writing-tests)
   - [Test File Organization](#test-file-organization)
@@ -22,6 +23,7 @@ Thank you for your interest in contributing to the `@node-core/doc-kit` project!
 - [Code Quality](#code-quality)
   - [Linting and Formatting](#linting-and-formatting)
   - [Pre-commit Hooks](#pre-commit-hooks)
+- [Releasing](#releasing)
 - [Commit Guidelines](#commit-guidelines)
 - [Developer's Certificate of Origin 1.1](#developers-certificate-of-origin-11)
 
@@ -151,6 +153,34 @@ The steps below will give you a general idea of how to prepare your local enviro
    node --run lint
    ```
 
+### Adding a Changeset
+
+This project uses [Changesets][] to manage versioning, the changelog, and npm releases. Any change
+that affects published behaviour should include a changeset so it shows up in `CHANGELOG.md` and
+triggers a release.
+
+1. **Create a changeset**
+
+   ```bash
+   node --run changeset
+   ```
+
+   You'll be prompted for the bump type and a short summary:
+   - **patch** — bug fixes and other backwards-compatible changes
+   - **minor** — new, backwards-compatible features
+   - **major** — breaking changes
+
+   The summary becomes the changelog entry, so write it for users of the package.
+
+2. **Commit the generated file**
+
+   This writes a Markdown file under `.changeset/`. Commit it alongside your code changes so it
+   lands with your Pull Request.
+
+> [!NOTE]
+> Changes that don't affect the published package (e.g. tests, CI, or internal docs) don't need a
+> changeset. See [Releasing](#releasing) for what happens to changesets after they're merged.
+
 ### Submitting Your Changes
 
 1. **Add and commit your changes**
@@ -303,6 +333,21 @@ You can bypass pre-commit hooks if necessary (not recommended):
 git commit -m "describe your changes" --no-verify
 ```
 
+## Releasing
+
+Releases are automated with [Changesets][] and require no manual version bumps — maintainers never
+edit the `version` field in `package.json` by hand.
+
+When changesets land on `main`, the [`Release` workflow](.github/workflows/release.yml) opens (or
+updates) a **"Version Packages"** Pull Request that consumes the pending changeset files, bumps the
+version in `package.json`, and writes the corresponding `CHANGELOG.md` entries.
+
+To ship a release, a maintainer merges that "Version Packages" PR. The same workflow then:
+
+- publishes `@node-core/doc-kit` to npm (via [npm trusted publishing][] — no token required),
+- creates the matching `v<x.y.z>` git tag, and
+- cuts a GitHub Release from the changelog.
+
 ## Commit Guidelines
 
 This project follows the [Conventional Commits][] specification.
@@ -327,6 +372,8 @@ By contributing to this project, I certify that:
   with this project or the open source license(s) involved.
 ```
 
+[Changesets]: https://github.com/changesets/changesets
 [Conventional Commits]: https://www.conventionalcommits.org/
 [Git]: https://git-scm.com/downloads
 [Husky]: https://typicode.github.io/husky/
+[npm trusted publishing]: https://docs.npmjs.com/trusted-publishers