Add changelog fragments

[cknitt]

Motivation

Today every user-facing PR adds a line directly to the (Unreleased) section of CHANGELOG.md. Because all those lines go into the same few sections, concurrent PRs constantly conflict on the changelog. That means rebasing only to resolve changelog conflicts, which is especially painful with stacked PRs. An entry can also end up in the wrong section, or under a version that has already been released, if the PR was opened before a release and merged after it. Nothing checks that a PR has an entry at all, and finalizing the changelog for a release is a manual edit.

Change

Release notes move into per-PR fragment files that never conflict, and they are collected into CHANGELOG.md only at release time.

How it works

• Each user-facing change adds changes/<description>.<category>.md (not changelog/, which yarn always packs into the npm package) with Markdown bullets that end in PR links. The categories are the existing CHANGELOG.md sections: breaking, feature, fix, docs, polish, internal. The unused Spec Compliance section is dropped; its only entry was in 10.1.0-rc.1. See changes/README.md.

  For example, changes/fix-watch-lock-removal.fix.md:

  - Fix `rescript watch` sometimes not exiting on macOS when `lib/watch.lock` is removed during a full rebuild. https://github.com/rescript-lang/rescript/pull/8730

  A fragment can hold several bullets of the same category. A bullet can wrap onto lines indented by two spaces and end with more than one PR link, as in changes/remove-deprecated-attributes.breaking.md:

  - Remove `@deriving(abstract)` and `@deriving(jsConverter)`.
    Use record types and polymorphic variants directly instead. https://github.com/rescript-lang/rescript/pull/8729
  - Remove the call-site `@inlined` attribute. https://github.com/rescript-lang/rescript/pull/8734 https://github.com/rescript-lang/rescript/pull/8736

• The PR number isn't known before the PR exists, so open it as a draft with the placeholder link https://github.com/rescript-lang/rescript/pull/XXXX, then replace it and mark the PR ready. Until then the check fails with:

  fix-watch-lock-removal.fix.md: replace the placeholder https://github.com/rescript-lang/rescript/pull/XXXX with the PR link
  

• A new Changelog workflow validates all fragments. On PRs, it also requires a newly added fragment and rejects edits to CHANGELOG.md.

• The workflow is separate from the main CI, so label changes rerun only this check.

• Release flow:

  • yarn changelog:preview shows pending notes.
  • yarn changelog:release inserts fragments into the unreleased section (newest PR first, existing entries kept), removes "(Unreleased)", and deletes the fragments.
  • yarn changelog:open adds the next empty unreleased section after the version bump.

  For example, with the fragment above and one existing entry, yarn changelog:release turns

  # 13.0.0-alpha.7 (Unreleased)
  ...
  #### :bug: Bug fix
  
  - Fix `RescriptTools.binaryPath` failing with `ERR_PACKAGE_IMPORT_NOT_DEFINED` when used from a user project. https://github.com/rescript-lang/rescript/pull/8694

  into

  # 13.0.0-alpha.7
  ...
  #### :bug: Bug fix
  
  - Fix `rescript watch` sometimes not exiting on macOS when `lib/watch.lock` is removed during a full rebuild. https://github.com/rescript-lang/rescript/pull/8730
  - Fix `RescriptTools.binaryPath` failing with `ERR_PACKAGE_IMPORT_NOT_DEFINED` when used from a user project. https://github.com/rescript-lang/rescript/pull/8694

  and deletes changes/fix-watch-lock-removal.fix.md.

• The Publish workflow refuses to release while fragments remain, so changes merged after release preparation can't ship without notes.

• CONTRIBUTING.md, AGENTS.md and a new PR template checklist document all this.

Alternatives considered

• towncrier, scriv: established fragment tools that work much like this. They would add Python to CI and the release flow.
• changie: the closest match, a single Go binary with configurable categories. It expects to own the changelog layout (per-version files merged into CHANGELOG.md).
• Changesets: built around per-package semver bumps rather than our categories, and it computes versions itself, which conflicts with versioning through yarn constraints.
• Release Drafter, GitHub's generated release notes, release-please, git-cliff: these generate notes from PR titles, labels or conventional commits. That avoids fragment files, but gives up hand-written entries or requires new title and commit conventions.

All of these would still need custom glue for the label-based PR check, the CHANGELOG.md guard, the Publish guard and our existing format. The custom script is about 200 lines with tests and no dependencies, and it keeps today's CHANGELOG.md format.

Labels (maintainer-applied, must exist in the repo)

• changelog:skip: no release notes needed. The fragment requirement is waived, but any fragment present is still validated.
• changelog:release: release preparation and opening the next section. It's the only label that allows editing CHANGELOG.md.
• Dependabot PRs are exempt automatically.

After merging

• Open PRs that edit CHANGELOG.md need to move their entry into a fragment.
• Existing unreleased entries in CHANGELOG.md stay as they are and are released with the next version.

Tests

• scripts/changelog.test.js covers:
  • fragment parsing, including the placeholder error
  • release insertion order and spacing, and notes containing $ patterns
  • the PR check with each label and Dependabot
  • opening the next section, then releasing it
• scripts/releasePlan.test.js adds a test for the leftover-fragment guard.
• yarn test-release-plan now runs in CI; nothing ran it before.

This PR removes the empty Spec Compliance heading from CHANGELOG.md, so it needs the changelog:release label rather than changelog:skip.

🤖 Generated with Claude Code

[pkg-pr-new]

Open in StackBlitz

rescript

npm i https://pkg.pr.new/rescript@8755

@rescript/belt

npm i https://pkg.pr.new/@rescript/belt@8755

@rescript/darwin-arm64

npm i https://pkg.pr.new/@rescript/darwin-arm64@8755

@rescript/darwin-x64

npm i https://pkg.pr.new/@rescript/darwin-x64@8755

@rescript/linux-arm64

npm i https://pkg.pr.new/@rescript/linux-arm64@8755

@rescript/linux-x64

npm i https://pkg.pr.new/@rescript/linux-x64@8755

@rescript/runtime

npm i https://pkg.pr.new/@rescript/runtime@8755

@rescript/win32-x64

npm i https://pkg.pr.new/@rescript/win32-x64@8755

commit: 184c38a

[github-actions]

Developer playground preview: https://rescript-lang.github.io/rescript/dev-playground/?version=pr-8755

[cknitt]

@codex review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-12T08:21:52.243780Z	344c258	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d91af0f1a5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[cknitt]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 09f63877d2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[cknitt]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 344c25857b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.40%. Comparing base (354d5a8) to head (184c38a).
⚠️ Report is 29 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #8755      +/-   ##
==========================================
+ Coverage   80.01%   80.40%   +0.39%     
==========================================
  Files         466      447      -19     
  Lines       63554    60984    -2570     
==========================================
- Hits        50854    49036    -1818     
+ Misses      12700    11948     -752     

see 139 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.