Skip to content

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

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 (1.12.0) and extra-files are unchanged and still match the code.
  2. CHANGELOG.md is new, seeded with the six releases release-please made so far (1.8.0 to 1.12.0). Each entry is the text release-please wrote in that release PR, in its own format. One line at the end points to GitHub Releases for older versions.
  3. DEVELOPMENT.md says the release PR now updates CHANGELOG.md, and how to flag a behaviour change with an override block.

How to flag a behaviour change

DEVELOPMENT.md describes the convention. Before merging a PR that changes behaviour for callers, end its body with release-please's commit override block (its begin and end markers are named in DEVELOPMENT.md). Put one line per changelog entry in it: the usual feat(...) or fix(...) line, then a behaviour(...) line that says what changes for callers. The behaviour line lands under "Behaviour Changes", at the top of the release entry.

Next to a feat or fix line, a behaviour line does not bump the version on its own: the feat or fix sets it. A behaviour line alone still makes a patch release, because it is a visible section.

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

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. With release-please 17.11.2 (the release-please-action v4.4.1 we pin allows ^17.3.0), its own changelog notes and changelog updater added a sample 1.13.0 entry 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.
  3. 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.

Out of scope

  1. The GitHub release page keeps GitHub's generated notes (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.

Every release so far lived only in GitHub Releases. release-please now
writes each release's notes to CHANGELOG.md, seeded with the releases it
made since 1.8.0, and a behaviour type lists caller-visible behaviour
changes first, under "Behaviour Changes".
@gonzalo-zenrows
gonzalo-zenrows merged commit bb9aa9c into main Nov 6, 2026
2 checks passed
@gonzalo-zenrows
gonzalo-zenrows deleted the ci/release-please-changelog branch November 6, 2026 11:27
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