Skip to content

Commit 98beeb5

Browse files
cknittclaude
andauthored
Add changelog fragments (#8755)
* Add changelog fragments Signed-off-by: Christoph Knittel <ck@cca.io> * Fix changelog fragment review findings Move the check to its own workflow, exempt Dependabot, insert notes newest PR first without splitting lists, and refuse to publish with leftover fragments. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Christoph Knittel <ck@cca.io> * Run release plan tests in CI Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Christoph Knittel <ck@cca.io> * Guard CHANGELOG.md edits and add changelog:open Reject CHANGELOG.md edits without changelog:release, explain the placeholder link and draft PR flow, and open the next unreleased section by command. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Christoph Knittel <ck@cca.io> * Turn the PR template into a short checklist Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Christoph Knittel <ck@cca.io> * Drop the unused Spec Compliance category It was used once, in 10.1.0-rc.1. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Christoph Knittel <ck@cca.io> * Move changelog fragments to changes/ Yarn always packs a root changelog directory, which would ship fragments in the npm package and break the artifact list check. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Christoph Knittel <ck@cca.io> * Collect late fragments into a finalized version Publish blocks on fragments merged after release preparation; rerunning changelog:release now adds them instead of failing on the finalized heading. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XJG88tCTovUPzEf2nxUPtq Signed-off-by: Christoph Knittel <ck@cca.io> * Keep late fragments out of tagged versions Publish tags vX before publishing, so a tagged version is treated as published and its notes are no longer extended. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XJG88tCTovUPzEf2nxUPtq Signed-off-by: Christoph Knittel <ck@cca.io> * Document not collecting notes during a Publish run Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XJG88tCTovUPzEf2nxUPtq Signed-off-by: Christoph Knittel <ck@cca.io> --------- Signed-off-by: Christoph Knittel <ck@cca.io> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent cb53311 commit 98beeb5

12 files changed

Lines changed: 631 additions & 9 deletions

File tree

‎.github/pull_request_template.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
## Checklist
2+
3+
- [ ] Added a changelog fragment (see `changes/README.md`), or no release notes are needed and a maintainer should apply `changelog:skip`.
4+
- [ ] Added tests for the fix or feature.
5+
- [ ] Signed off every commit for the DCO (`git commit -s`).

‎.github/workflows/changelog.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
name: Changelog
2+
3+
on:
4+
push:
5+
branches: [master, 11.0_release]
6+
7+
# Label events rerun only this check, so applying changelog:skip or
8+
# changelog:release does not restart the main CI.
9+
pull_request:
10+
types: [opened, synchronize, reopened, labeled, unlabeled]
11+
branches: [master, 11.0_release]
12+
13+
concurrency:
14+
group: changelog-${{ github.ref }}
15+
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
16+
17+
permissions:
18+
contents: read
19+
20+
jobs:
21+
changelog:
22+
runs-on: ubuntu-24.04
23+
steps:
24+
- uses: actions/checkout@v7
25+
with:
26+
fetch-depth: 0
27+
ref: ${{ github.event.pull_request.head.sha || github.sha }}
28+
- uses: actions/setup-node@v6
29+
with:
30+
node-version: 22
31+
- run: node --test scripts/changelog.test.js
32+
- run: node scripts/changelog.js check

‎.github/workflows/ci.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -190,6 +190,9 @@ jobs:
190190
- name: Version Check
191191
run: yarn constraints
192192

193+
- name: Test release plan
194+
run: yarn test-release-plan
195+
193196
- name: Run tests
194197
run: node scripts/test.js -all
195198

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@ on `master`. CI runs on every PR in the stack.
9797

9898
## Testing and changelog
9999

100-
**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.
100+
**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`).
101101

102102
For compiler or standard-library changes, run `make test`. For syntax changes,
103103
also run `make test-syntax`; use `make test-syntax-roundtrip` when parsing or

‎CHANGELOG.md‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@
33
> **Tags:**
44
>
55
> - :boom: [Breaking Change]
6-
> - :eyeglasses: [Spec Compliance]
76
> - :rocket: [New Feature]
87
> - :bug: [Bug Fix]
98
> - :memo: [Documentation]
@@ -19,8 +18,6 @@
1918
- 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
2019
- 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
2120

22-
#### :eyeglasses: Spec Compliance
23-
2421
#### :rocket: New Feature
2522

2623
- Support Windows 11 on ARM by installing the x64 binaries, which Windows runs through its x64 emulation. https://github.com/rescript-lang/rescript/pull/8776

‎CONTRIBUTING.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -510,7 +510,7 @@ Adding a new entry there requires re-running the analysis tests. Follow these st
510510

511511
(If a `make` command fails, consider using the [DevContainer](#b-devcontainer).)
512512

513-
Finally, add a line to [CHANGELOG.md](CHANGELOG.md), using the `#### :nail_care: Polish` section.
513+
Finally, add a `changes/<description>.polish.md` fragment following [the changelog instructions](changes/README.md).
514514

515515
## Code structure
516516

@@ -572,7 +572,7 @@ The repository's `npm-release` GitHub environment should have required reviewers
572572
To build a new version and release it on NPM, follow these steps:
573573

574574
1. Verify that the version number is already set correctly for the release. (It should have been incremented after releasing the previous version.)
575-
1. Create a PR to update `CHANGELOG.md`, removing the "(Unreleased)" for the version to be released.
575+
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.
576576
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:
577577
- A current stable release is published as `latest`.
578578
- 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:
585585
1. Create a PR with the following changes to prepare for development of the next version:
586586
- Increment the `EXPECTED_VERSION` number in `yarn.config.cjs` for the next version.
587587
- Run `yarn constraints --fix` to take that version number over into other files.
588-
- Update `CHANGELOG.md` and add an entry for the next version, e.g., "10.0.0-beta.2 (Unreleased)"
588+
- 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.
589589

590590
## Debugging issues from CI builds
591591

‎changes/README.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Changelog fragments
2+
3+
Add a unique `<description>.<category>.md` file for each change that needs release notes. For example, `fix-watcher-recovery.fix.md`:
4+
5+
```markdown
6+
- Recover blocked dependents after a failed build. https://github.com/rescript-lang/rescript/pull/8667
7+
```
8+
9+
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.
10+
11+
| Category | Section |
12+
| --- | --- |
13+
| `breaking` | Breaking Change |
14+
| `feature` | New Feature |
15+
| `fix` | Bug fix |
16+
| `docs` | Documentation |
17+
| `polish` | Polish |
18+
| `internal` | Internal |
19+
20+
`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.
21+
22+
`yarn changelog:preview` prints pending fragments grouped by category, newest PR first, without changing files. It does not include entries already in `CHANGELOG.md`.
23+
24+
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.
25+
26+
After publishing, run `yarn changelog:open` once `package.json` has the next version. It adds an empty unreleased section with every category heading.
27+
28+
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‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,12 @@
5656
"check:all": "biome check .",
5757
"format": "biome check --no-errors-on-unmatched . --fix",
5858
"typecheck": "tsc",
59-
"apidocs:generate": "yarn workspace @utils/scripts apidocs:generate"
59+
"apidocs:generate": "yarn workspace @utils/scripts apidocs:generate",
60+
"changelog:check": "node scripts/changelog.js check",
61+
"changelog:preview": "node scripts/changelog.js preview",
62+
"changelog:release": "node scripts/changelog.js release",
63+
"changelog:open": "node scripts/changelog.js open",
64+
"test-changelog": "node --test scripts/changelog.test.js"
6065
},
6166
"files": [
6267
"CHANGELOG.md",

0 commit comments

Comments
 (0)