Skip to content

ci: let release-please maintain CHANGELOG.md - #65

Merged
gonzalo-zenrows merged 1 commit into
mainfrom
ci/release-please-changelog
Nov 6, 2026
Merged

gonzalo-zenrows merged 1 commit into
mainfrom
ci/release-please-changelog

Conversation

@gonzalo-zenrows

Copy link
Copy Markdown
Contributor

release-please now writes a CHANGELOG.md entry with every release, and a change in behaviour that callers must know about gets its own section at the top of that entry.

This PR releases nothing. ci is a hidden type, so release-please opens no release PR for it. The next release PR, for the next feat or fix, is the first one that writes to CHANGELOG.md.

What changes

  1. release-please-config.json: skip-changelog is now false, and a new section behaviour ("Behaviour Changes") is listed first in changelog-sections. Nothing else in the config changes. .release-please-manifest.json (2.6.0) is unchanged.
  2. CHANGELOG.md is new, seeded with the four releases release-please made so far (2.4.0 to 2.6.0). Each entry is what release-please writes for that release, in its own format: the feat and fix commits, with their PR and commit links and the release date. One line at the end points to GitHub Releases for older versions.
  3. The README's Releases section says that the release PR now updates CHANGELOG.md, and how to flag a behaviour change with a commit override block in the PR body.
  4. npm already ships CHANGELOG.md: the package uses .npmignore, not a files list, and npm pack --dry-run lists it.

How to flag a behaviour change

The README's Releases section shows the block. In short: before merging, end the PR body with a commit override block that holds one feat or fix line and one behaviour line. Each line becomes one changelog entry.

A behaviour line never asks for a minor or major release. The feat or fix line next to it sets the version. On its own, without a feat or fix, it would still open a patch release, because it is a visible section.

This body describes the block in words on purpose. release-please reads the first override block it finds in a merged PR's body, even inside a code fence, so an example block here would rewrite this PR's own changelog entry.

How it was checked

  1. The config parses as JSON and is valid against the release-please config schema, both the one at the $schema URL and the one shipped in release-please 17.11.2. The manifest is valid against its schema too.
  2. The seeded entries were generated with release-please 17.11.2's own changelog notes code, from the real commits between each pair of tags, with this branch's changelog-sections. Only the dates were set by hand, to each release's date.
  3. With release-please 17.11.2 (the release-please-action v4.4.1 we pin allows ^17.3.0), its changelog updater added a sample 2.7.0 entry with one feat and one behaviour line to the seeded file. The entry landed right under # Changelog, with "Behaviour Changes" above "Features", and the seeded entries and the last line stayed in place below it.
  4. release-please release-pr --dry-run against main found no unreleased commits and would open no PR. It reads the config from the remote branch, so it does not exercise this branch's config.
  5. pnpm check passes.

Out of scope

  1. The GitHub release page keeps GitHub's generated notes, because the release workflow overwrites them. So a "Behaviour Changes" entry shows in CHANGELOG.md and in the release PR, not on the GitHub release page.
  2. The seeded entries list only feat and fix changes, as release-please does. The ci, docs and test changes in those releases stay on their GitHub release pages.
  3. The npm package also ships .github/ and the release-please files, because .npmignore does not exclude them. This PR does not change that.

Turn skip-changelog off, so each release PR also writes its notes to
CHANGELOG.md, and add a "Behaviour Changes" section, listed first, for
the custom commit type behaviour. A merged PR states a behaviour change
through a commit override block in its body.

Seed CHANGELOG.md with the four releases made by release-please (2.4.0
to 2.6.0), in release-please's own format, so the next release PR
inserts its entry above them. A last line points to GitHub Releases for
older versions. The README's Releases section says how to flag a
behaviour change.
@gonzalo-zenrows
gonzalo-zenrows merged commit e4d6191 into main Nov 6, 2026
2 checks passed
@gonzalo-zenrows
gonzalo-zenrows deleted the ci/release-please-changelog branch November 6, 2026 11:28
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