From 4d5e5a5fd57b83a497f4e67c56681b3fe3df9f02 Mon Sep 17 00:00:00 2001
From: Ben Vinegar <ben@benv.ca>
Date: Sat, 13 Jun 2026 10:48:40 -0400
Subject: [PATCH] chore(release): adopt changesets

---
 .changeset/README.md             | 31 +++++++++++++++++++++++++++++++
 .changeset/chilly-diffs-dance.md |  5 +++++
 .changeset/config.json           | 16 ++++++++++++++++
 .github/workflows/pr-ci.yml      | 19 +++++++++++++++++++
 AGENTS.md                        | 11 ++++-------
 CHANGELOG.md                     | 10 ----------
 CONTRIBUTING.md                  | 15 +++++++++++++++
 package.json                     |  4 ++++
 8 files changed, 94 insertions(+), 17 deletions(-)
 create mode 100644 .changeset/README.md
 create mode 100644 .changeset/chilly-diffs-dance.md
 create mode 100644 .changeset/config.json

diff --git a/.changeset/README.md b/.changeset/README.md
new file mode 100644
index 00000000..80d8a816
--- /dev/null
+++ b/.changeset/README.md
@@ -0,0 +1,31 @@
+# Changesets
+
+Hunk uses [Changesets](https://github.com/changesets/changesets) for release-note fragments and npm version preparation.
+
+For user-visible changes, add a changeset instead of editing `CHANGELOG.md` directly:
+
+```bash
+bun run changeset
+```
+
+Select `hunkdiff` and choose the semver bump that matches the shipped CLI/package change:
+
+- `patch` for fixes and small behavior changes
+- `minor` for new user-facing features
+- `major` for breaking changes
+
+`package.json` intentionally lists `"."` in `workspaces` so Changesets can discover the root `hunkdiff` package. Keep that entry unless Hunk moves the publishable package out of the repository root.
+
+For maintenance-only PRs that should not appear in release notes, create an empty changeset:
+
+```bash
+bun run changeset -- --empty
+```
+
+Release prep runs:
+
+```bash
+bun run release:version
+```
+
+That consumes the pending `.changeset/*.md` files, updates `CHANGELOG.md`, and bumps package versions for the release commit.
diff --git a/.changeset/chilly-diffs-dance.md b/.changeset/chilly-diffs-dance.md
new file mode 100644
index 00000000..a034c4b5
--- /dev/null
+++ b/.changeset/chilly-diffs-dance.md
@@ -0,0 +1,5 @@
+---
+"hunkdiff": patch
+---
+
+Adopt Changesets for release-note fragments so pull requests can avoid conflicting `CHANGELOG.md` edits.
diff --git a/.changeset/config.json b/.changeset/config.json
new file mode 100644
index 00000000..28369925
--- /dev/null
+++ b/.changeset/config.json
@@ -0,0 +1,16 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.4/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": [
+    "@hunk/session-broker",
+    "@hunk/session-broker-bun",
+    "@hunk/session-broker-core",
+    "@hunk/session-broker-node"
+  ]
+}
diff --git a/.github/workflows/pr-ci.yml b/.github/workflows/pr-ci.yml
index 3887c047..e16ce7ea 100644
--- a/.github/workflows/pr-ci.yml
+++ b/.github/workflows/pr-ci.yml
@@ -27,6 +27,25 @@ jobs:
           HEAD_SHA: ${{ github.sha }}
         run: .github/scripts/detect-code-changes.sh "$BASE_SHA" "$HEAD_SHA"
 
+  changeset-status:
+    name: Release-note changeset
+    needs: changes
+    if: needs.changes.outputs.code == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: 1.3.10
+
+      - name: Verify release-note changeset
+        run: bun run changeset:status -- --since=origin/main
+
   windows-compat:
     name: Windows compatibility
     needs: changes
diff --git a/AGENTS.md b/AGENTS.md
index b38305f3..b56f33d6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -132,13 +132,10 @@ CLI input
 
 ## releases
 
-- Maintain the top-level `CHANGELOG.md` as the source of truth for user-visible changes.
-- Keep upcoming work under `## [Unreleased]` with these subsections:
-  - `### Added`
-  - `### Changed`
-  - `### Fixed`
-- Append to existing subsections instead of creating duplicates.
-- When cutting a release, move the relevant unreleased entries into a new immutable version section and start a fresh `## [Unreleased]` section.
+- Use Changesets for user-visible release notes. Add a `.changeset/*.md` entry with `bun run changeset` instead of editing `CHANGELOG.md` directly.
+- Target the public `hunkdiff` package in changesets. Use `patch` for fixes and small behavior changes, `minor` for new user-facing features, and `major` for breaking changes.
+- For maintenance-only PRs that should not appear in release notes, add an empty changeset with `bun run changeset -- --empty`.
+- Keep the top-level `CHANGELOG.md` as the released changelog artifact. It is updated during release prep with `bun run release:version`, not by normal feature/fix PRs.
 - Use the released changelog section as the starting point for the GitHub release body.
 - GitHub releases should follow this format:
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e1bb0f70..b8ad99f1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,15 +1,5 @@
 # Changelog
 
-All notable user-visible changes to Hunk are documented in this file.
-
-## [Unreleased]
-
-### Added
-
-### Changed
-
-### Fixed
-
 ## [0.15.3] - 2026-06-13
 
 ### Added
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 91956e84..4ac37ce3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -154,4 +154,19 @@ Key rules:
 
 - The npm package name is `hunkdiff`.
 - The installed CLI command remains `hunk`.
+- Add a Changeset for user-visible changes instead of editing `CHANGELOG.md` directly:
+
+  ```bash
+  bun run changeset
+  ```
+
+  Select `hunkdiff`, then choose `patch` for fixes and small behavior changes, `minor` for new user-facing features, or `major` for breaking changes.
+
+- For maintenance-only PRs that should not appear in release notes, add an empty changeset:
+
+  ```bash
+  bun run changeset -- --empty
+  ```
+
+- Release prep runs `bun run release:version` to consume pending changesets, update `CHANGELOG.md`, and bump package versions.
 - The automated prebuilt publish workflow lives in `.github/workflows/release-prebuilt-npm.yml`.
diff --git a/package.json b/package.json
index 62892c6c..6131646b 100644
--- a/package.json
+++ b/package.json
@@ -24,6 +24,7 @@
     "hunkdiff": "./bin/hunk.cjs"
   },
   "workspaces": [
+    ".",
     "packages/*"
   ],
   "files": [
@@ -58,6 +59,9 @@
     "format:check": "oxfmt --check .",
     "lint": "oxlint . --deny-warnings",
     "lint:fix": "oxlint . --fix",
+    "changeset": "bunx @changesets/cli@2.31.0",
+    "changeset:status": "bunx @changesets/cli@2.31.0 status",
+    "release:version": "bunx @changesets/cli@2.31.0 version",
     "prepare": "simple-git-hooks",
     "test": "\"${npm_execpath:-bun}\" test ./src ./packages ./scripts ./test/cli ./test/session",
     "test:integration": "\"${npm_execpath:-bun}\" test ./test/pty",