Add changelog fragments

.github/pull_request_template.md

@@ -0,0 +1,5 @@
+## Checklist
+
+- [ ] Added a changelog fragment (see `changes/README.md`), or no release notes are needed and a maintainer should apply `changelog:skip`.
+- [ ] Added tests for the fix or feature.
+- [ ] Signed off every commit for the DCO (`git commit -s`).

.github/workflows/changelog.yml

@@ -0,0 +1,32 @@
+name: Changelog
+
+on:
+  push:
+    branches: [master, 11.0_release]
+
+  # Label events rerun only this check, so applying changelog:skip or
+  # changelog:release does not restart the main CI.
+  pull_request:
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+    branches: [master, 11.0_release]
+
+concurrency:
+  group: changelog-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  changelog:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+      - run: node --test scripts/changelog.test.js
+      - run: node scripts/changelog.js check

.github/workflows/ci.yml

@@ -190,6 +190,9 @@ jobs:
       - name: Version Check
         run: yarn constraints
 
+      - name: Test release plan
+        run: yarn test-release-plan
+
       - name: Run tests
         run: node scripts/test.js -all
 

AGENTS.md

@@ -92,7 +92,7 @@ on `master`. CI runs on every PR in the stack.
 
 ## Testing and changelog
 
-**Add a `CHANGELOG.md` entry** for any user-facing change (bug fix, feature, or breaking change). Put it under the matching section of the current `(Unreleased)` version and end the line with the PR link. See [CONTRIBUTING.md](CONTRIBUTING.md). PRs are expected to include one.
+**Add a changelog fragment** `changes/<description>.<category>.md` for any user-facing change (bug fix, feature, or breaking change) instead of editing `CHANGELOG.md`; see [changes/README.md](changes/README.md) for categories and format. Validate with `yarn changelog:check`. Since the PR number is not known yet, open the PR as a draft with the placeholder link `https://github.com/rescript-lang/rescript/pull/XXXX`, then replace it with the real link, amend, push again, and mark the PR ready for review (`gh pr ready`).
 
 For compiler or standard-library changes, run `make test`. For syntax changes,
 also run `make test-syntax`; use `make test-syntax-roundtrip` when parsing or

CHANGELOG.md

@@ -3,7 +3,6 @@
 > **Tags:**
 >
 > - :boom: [Breaking Change]
-> - :eyeglasses: [Spec Compliance]
 > - :rocket: [New Feature]
 > - :bug: [Bug Fix]
 > - :memo: [Documentation]
@@ -18,8 +17,6 @@
 - Remove the call-site `@inlined` attribute, which was parsed but never affected code generation. It is now reported as a misplaced attribute (warning 53). https://github.com/rescript-lang/rescript/pull/8734
 - Remove `@deriving(abstract)` and `@deriving(jsConverter)`. Use record types (with optional fields, mutable fields and `@as` renaming) and polymorphic variants directly instead. https://github.com/rescript-lang/rescript/pull/8729
 
-#### :eyeglasses: Spec Compliance
-
 #### :rocket: New Feature
 
 #### :bug: Bug fix

CONTRIBUTING.md

@@ -510,7 +510,7 @@ Adding a new entry there requires re-running the analysis tests. Follow these st
 
 (If a `make` command fails, consider using the [DevContainer](#b-devcontainer).)
 
-Finally, add a line to [CHANGELOG.md](CHANGELOG.md), using the `#### :nail_care: Polish` section.
+Finally, add a `changes/<description>.polish.md` fragment following [the changelog instructions](changes/README.md).
 
 ## Code structure
 
@@ -572,7 +572,7 @@ The repository's `npm-release` GitHub environment should have required reviewers
 To build a new version and release it on NPM, follow these steps:
 
 1. Verify that the version number is already set correctly for the release. (It should have been incremented after releasing the previous version.)
-1. Create a PR to update `CHANGELOG.md`, removing the "(Unreleased)" for the version to be released.
+1. Run `yarn changelog:preview` to review pending notes, then `yarn changelog:release` to collect fragments into `CHANGELOG.md`, remove "(Unreleased)", and delete consumed fragments. Create a PR containing these changes, review the combined release notes, and apply the `changelog:release` label. Existing unreleased entries are preserved. If more fragments are merged before publishing, the `Publish` workflow refuses to run; repeat this step to add them to the same version. Don't run `yarn changelog:release` while a `Publish` run is in progress: it could add notes for changes that the run is not publishing.
 1. Once that PR is merged and built successfully, run the `Publish` workflow from the GitHub Actions tab. Use the "Run workflow" branch dropdown to select the release branch (normally `master`, or the relevant maintenance branch) and indicate whether this is the current stable release. The version is read from that branch's `package.json`, and the npm tag is derived automatically:
    - A current stable release is published as `latest`.
    - A stable maintenance release for an older major is published as `latest-<major>`, for example `latest-12`.
@@ -585,7 +585,7 @@ To build a new version and release it on NPM, follow these steps:
 1. Create a PR with the following changes to prepare for development of the next version:
    - Increment the `EXPECTED_VERSION` number in `yarn.config.cjs` for the next version.
    - Run `yarn constraints --fix` to take that version number over into other files.
-   - Update `CHANGELOG.md` and add an entry for the next version, e.g., "10.0.0-beta.2 (Unreleased)"
+   - Run `yarn changelog:open` to add the empty "(Unreleased)" section for the next version to `CHANGELOG.md`, and apply the `changelog:release` label to the PR.
 
 ## Debugging issues from CI builds
 

changes/README.md

@@ -0,0 +1,28 @@
+# Changelog fragments
+
+Add a unique `<description>.<category>.md` file for each change that needs release notes. For example, `fix-watcher-recovery.fix.md`:
+
+```markdown
+- Recover blocked dependents after a failed build. https://github.com/rescript-lang/rescript/pull/8667
+```
+
+The PR number is only known once the PR exists, so open it as a draft with the placeholder link `https://github.com/rescript-lang/rescript/pull/XXXX`, replace the placeholder with the real link, amend and push again, then mark the PR ready for review. The changelog check fails while the placeholder remains. Each file may contain multiple bullets in the same category. Indent wrapped lines by two spaces; each bullet ends with one or more PR links.
+
+| Category | Section |
+| --- | --- |
+| `breaking` | Breaking Change |
+| `feature` | New Feature |
+| `fix` | Bug fix |
+| `docs` | Documentation |
+| `polish` | Polish |
+| `internal` | Internal |
+
+`yarn changelog:check` validates all fragments. CI requires a newly added fragment relative to the PR merge base, and rejects edits to `CHANGELOG.md` unless the PR has the `changelog:release` label. Maintainers may apply `changelog:skip` when notes are unnecessary, or `changelog:release` for release preparation. These labels, like Dependabot PRs, are exempt from the requirement, but never from fragment validation. Reviewers decide whether the chosen category is appropriate.
+
+`yarn changelog:preview` prints pending fragments grouped by category, newest PR first, without changing files. It does not include entries already in `CHANGELOG.md`.
+
+During release preparation, run `yarn changelog:release`. It verifies that the first version heading matches `package.json` and is unreleased, validates every fragment before writing, adds fragments above the existing entries of each section, newest PR first, removes `(Unreleased)`, and deletes consumed files. Review and commit all changes in the release PR. Historical entries and existing unreleased notes are preserved. Releases with no fragments can still finalize existing notes. The publish workflow refuses to release while fragments remain in `changes/`. If fragments are merged after the release PR but before publishing, run `yarn changelog:release` again: as long as Publish has not created the version's `v<version>` tag, it adds them to the finalized version. Once the tag exists, it refuses, and the fragments wait for the next version after `yarn changelog:open`. With no fragments left, running it again fails. Don't run it while a Publish run is in progress, because the tag only appears once that run gets to tagging, and the notes could then describe changes the run is not publishing.
+
+After publishing, run `yarn changelog:open` once `package.json` has the next version. It adds an empty unreleased section with every category heading.
+
+Only release preparation and opening the next unreleased section should edit `CHANGELOG.md`, in PRs labelled `changelog:release`. Keep fragments on the branch containing the associated change; backports should include their fragments if they need notes in the maintenance release.

package.json

@@ -56,7 +56,12 @@
     "check:all": "biome check .",
     "format": "biome check --no-errors-on-unmatched . --fix",
     "typecheck": "tsc",
-    "apidocs:generate": "yarn workspace @utils/scripts apidocs:generate"
+    "apidocs:generate": "yarn workspace @utils/scripts apidocs:generate",
+    "changelog:check": "node scripts/changelog.js check",
+    "changelog:preview": "node scripts/changelog.js preview",
+    "changelog:release": "node scripts/changelog.js release",
+    "changelog:open": "node scripts/changelog.js open",
+    "test-changelog": "node --test scripts/changelog.test.js"
   },
   "files": [
     "CHANGELOG.md",