Skip to content

fix(release): fold the beta changelog into the release that supersedes it - #219

Merged
derrickmehaffy merged 1 commit into
mainfrom
fix/changelog-consolidate-prereleases
Aug 14, 2026
Merged

fix(release): fold the beta changelog into the release that supersedes it#219
derrickmehaffy merged 1 commit into
mainfrom
fix/changelog-consolidate-prereleases

Conversation

@derrickmehaffy

Copy link
Copy Markdown
Contributor

You're right — as it stands the 5.1.0 release PR reads as though almost nothing
shipped:

## [5.1.0]        Bug Fixes, Documentation, Chores        →  3 entries
## [5.1.0-beta]   Features, Bug Fixes, Performance, …     → 33 entries

release-please writes one section per release, and a prerelease is a release.
So everything that actually went into 5.1.0 sits under a heading for a version
almost nobody installed. Anyone upgrading 5.0.1 → 5.1.0 wants one list.

Fix

Prerelease sections are folded into the stable release sharing their
major.minor.patch, with subsections restored to the order
changelog-sections declares — merging appends whole groups, so without that a
reader meets Chores before Features. The compare link widens to where
the earliest prerelease began, since the stable release now spans it:

compare/v5.1.0-beta...v5.1.0   →   compare/v5.0.0...v5.1.0

Only the topmost section is considered — the release being prepared. My
first version folded every stable release and rewrote history: it merged the
2022 4.0.0-alpha.0 and 4.0.0-alpha.1 sections into 4.0.0, losing which
alpha introduced what, in releases that shipped years ago.

A second bug, found while wiring it up

The step's RELEASE_BRANCH was hardcoded to release-please--branches--main.
That stopped being the release branch when #216 removed
separate-pull-requests: false and the strategy started naming its own —
release-please--branches--main--components--monorepo.

A hardcoded name doesn't fail, it silently skips: the git ls-remote guard
simply found nothing, so the changelog was quietly going untidied. It is now
read from the open release pull request, so it survives future config changes.

Verified against the real release branch

resolved branch: release-please--branches--main--components--monorepo
folded 1 prerelease section into its stable release
no duplicates found
5.1.0 entries: 36        (3 + 33, nothing lost)
  • subsections in canonical order: Features, Bug Fixes, Performance, Refactoring, Documentation, Chores
  • the two 4.0.0-alpha sections untouched
  • a second run reports no prerelease sections to fold — idempotent
  • the deduplicator finds nothing left afterwards, and max consecutive blank lines is 2

Note

This is general, not a one-off patch — but it should rarely fire again. Betas
are now manual dispatches that publish to npm without a tag or a GitHub Release,
so they no longer produce changelog sections at all.

🤖 Generated with Claude Code

…s it

The 5.1.0 release PR reads as though almost nothing shipped:

  ## [5.1.0]        Bug Fixes, Documentation, Chores       - 3 entries
  ## [5.1.0-beta]   Features, Bug Fixes, Performance, ...  - 33 entries

release-please writes one section per release and a prerelease is a release, so
everything that went into 5.1.0 sits under a heading for a version almost
nobody installed. Someone upgrading 5.0.1 -> 5.1.0 wants one list.

Prerelease sections are now folded into the stable release with the same
major.minor.patch, with the subsections put back into the order
changelog-sections declares - merging appends whole groups, so without that a
reader meets Chores before Features. The compare link widens to where the
earliest prerelease started, since the stable release now spans it.

Only the topmost section is considered, which is the release being prepared.
Folding every stable release rewrote history on the first run: it merged the
2022 4.0.0-alpha.0 and 4.0.0-alpha.1 sections into 4.0.0 and lost which alpha
introduced what, in releases that shipped years ago.

Also fixes the branch name this step works on. It was hardcoded to
`release-please--branches--main`, which stopped being the release branch when
removing `separate-pull-requests: false` gave the strategy its own name -
`release-please--branches--main--components--monorepo`. A hardcoded name does
not fail, it silently skips, so the changelog was quietly going untidied. It is
now read from the open release pull request.

Verified against the real release branch: 3 + 33 = 36 entries with none lost,
subsections in canonical order, the 4.0.0 alphas untouched, a second run a
no-op, and the deduplicator finding nothing left to remove afterwards.

Co-Authored-By: Claude <noreply@anthropic.com>
@derrickmehaffy
derrickmehaffy merged commit 5ee1bae into main Aug 14, 2026
4 of 12 checks passed
@derrickmehaffy
derrickmehaffy deleted the fix/changelog-consolidate-prereleases branch August 14, 2026 05:20
@github-actions github-actions Bot mentioned this pull request Aug 14, 2026
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.

1 participant