Skip to content

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

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 users 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. extra-files (src/core/config.ts) and .release-please-manifest.json (1.12.0) are unchanged.
  2. CHANGELOG.md is new, seeded with the eleven releases the release-please flow made so far (1.5.4 to 1.12.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. package.json: CHANGELOG.md joins the files list, so the npm package ships it.
  4. docs/contributing.md (Releases) says that the release PR now updates CHANGELOG.md, and shows how to flag a behaviour change with release-please's commit-override block in the PR body.

How to flag a behaviour change

docs/contributing.md shows the block. In short: before merging, end the PR body with release-please's commit-override block, holding one feat or fix line and one behaviour line. Each line becomes one changelog entry.

A behaviour line does not bump the version on its own next to a feat or fix: that line sets the version. Alone, without a feat or fix, it still opens a patch release, because it is a visible section.

This body describes the block in words on purpose. release-please reads the first commit-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 config schema shipped in release-please 17.11.2.
  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 (UTC).
  3. With release-please 17.11.2, its changelog updater added a sample 1.13.0 entry to the seeded file. The entry landed right under # Changelog, and the seeded entries and the last line stayed unchanged below it. A sample feat plus behaviour override rendered "Behaviour Changes" above "Features", and released 1.13.0.
  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. npm run typecheck and npm test are not affected: no code changes.

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.

Release notes lived only on GitHub Releases, so nobody reading the package
or the repo could see what changed between versions.

release-please now writes CHANGELOG.md on every release PR. A new
"Behaviour Changes" section, listed first, takes behaviour(scope) lines
from a PR body's override block. CHANGELOG.md is seeded with the releases
the release-please flow made, 1.5.4 to 1.12.0, in the format release-please
writes, so the next release inserts its entry above them.
@gonzalo-zenrows
gonzalo-zenrows merged commit 78de0df into main Nov 6, 2026
3 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