Skip to content

ci: Add action to validate changelog diffs after merging#7525

Merged
Mrtenz merged 16 commits into
mainfrom
mrtenz/validate-changelog-diffs
Mar 26, 2026
Merged

ci: Add action to validate changelog diffs after merging#7525
Mrtenz merged 16 commits into
mainfrom
mrtenz/validate-changelog-diffs

Conversation

@Mrtenz
Copy link
Copy Markdown
Member

@Mrtenz Mrtenz commented Dec 17, 2025

Explanation

This fixes an issue in changelogs where changelog entries may be incorrectly moved after merging into the main branch. Given the following (partial) changelog for example:

## [Unreleased]

### Changed

- Changelog entry A ([#1234](...))
- Changelog entry B ([#5678](...))
- Changelog entry C ([#1337](...))

After a release, this changelog may look like this:

  ## [Unreleased]

+ ## [1.0.0]

  ### Changed

  - Changelog entry A ([#1234](...))
  - Changelog entry B ([#5678](...))
  - Changelog entry C ([#1337](...))

But if another PR based on the original changelog also adds an entry to the unreleased section like this:

  ## [Unreleased]

  ### Changed

  - Changelog entry A ([#1234](...))
  - Changelog entry B ([#5678](...))
  - Changelog entry C ([#1337](...))
+ - Changelog entry D ([#0000](...))

The final changelog will look like this, since Git can merge the entry based on the other entries around it:

## [Unreleased]

## [1.0.0]

### Changed

- Changelog entry A ([#1234](...))
- Changelog entry B ([#5678](...))
- Changelog entry C ([#1337](...))
- Changelog entry D ([#0000](...))

Here it appears that the release included "entry D", but in reality that was meant to be under the unreleased section.

To address this issue, I've added a simple workflow that checks for changelog diffs. It uses a minimal algorithm to parse the markdown files, find entries that are included in unreleased originally, and checks if they still are after merging. If not, the workflow will fail and show an error such as this:

Checking changelog file: packages/some-package/CHANGELOG.md
The following lines added in the PR are missing from the "Unreleased" section after merge:

  • Changelog entry D (#0000)

Please update your pull request and ensure that new changelog entries remain in the "Unreleased" section.

Long term we should solve this problem by using changesets instead, in which case the unreleased changes will never be merged or conflict with each other, but until we figure out how to implement those in our release workflows, we can use this workflow.

References

Checklist

  • I've updated the test suite for new or updated code as appropriate
  • I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
  • I've communicated my changes to consumers by updating changelogs for packages I've changed
  • I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

Note

Low Risk
Low risk CI-only change that adds a new workflow gate; main failure mode is false positives/negatives that could block merges.

Overview
Adds a new composite GitHub Action (check-merge-queue-changelogs) and Node script to detect when changelog lines introduced in a PR get moved out of the ## [Unreleased] section after merge (a common merge-queue conflict artifact).

Updates lint-build-test.yml to run a new validate-changelog-diffs job on pull_request and merge_group events, failing the workflow when modified CHANGELOG.md files lose newly-added Unreleased entries in the merged result.

Written by Cursor Bugbot for commit ef5a189. This will update automatically on new commits. Configure here.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a plain JS file so we can just call node check-changelog-diff.cjs without installing dependencies etc.

@Mrtenz Mrtenz marked this pull request as ready for review December 18, 2025 09:39
@Mrtenz Mrtenz requested a review from a team as a code owner December 18, 2025 09:39
Comment thread .github/actions/check-merge-queue-changelogs/check-changelog-diff.cjs Outdated
Comment thread .github/actions/check-merge-queue-changelogs/action.yml
Comment thread .github/actions/check-merge-queue-changelogs/action.yml Outdated
Comment thread .github/actions/check-merge-queue-changelogs/action.yml Outdated
Comment thread .github/actions/check-merge-queue-changelogs/action.yml
Comment thread .github/actions/check-merge-queue-changelogs/action.yml Outdated
@Mrtenz Mrtenz requested a review from Gudahtt March 26, 2026 11:29
Copy link
Copy Markdown

@cursor cursor Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Fix All in Cursor

Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.

Comment thread .github/workflows/lint-build-test.yml Outdated
Comment thread .github/actions/check-merge-queue-changelogs/check-changelog-diff.cjs Outdated
Gudahtt
Gudahtt previously approved these changes Mar 26, 2026
Copy link
Copy Markdown
Member

@Gudahtt Gudahtt left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! I had a couple of minor questions but no blockers

@Mrtenz Mrtenz added this pull request to the merge queue Mar 26, 2026
Merged via the queue into main with commit fc38e95 Mar 26, 2026
327 checks passed
@Mrtenz Mrtenz deleted the mrtenz/validate-changelog-diffs branch March 26, 2026 16:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants