Repository navigation
docs: document trigger conditions for duplicate changelog entries - #47
Merged
Merged
Conversation
Research into googleapis/release-please#2476 and the splitMessages() implementation shows the duplication is deterministic: release-please deliberately splits commit bodies on paragraph-leading Conventional Commits lines, so a plain merge commit whose PR title is in Conventional Commits form with a changelog-visible type duplicates the branch commits' entries. Earlier merges that seemed equivalent did not duplicate because their types are hidden from the changelog (chore/ci/docs) or they predate release-please's scan range. Replace the "trigger conditions are not fully understood" wording in RELEASING.md and ADR-010 with the identified conditions. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
… practices Record the full research behind the trigger-condition update: the splitMessages() mechanism and its regex subtleties, why Electron/Vite/ Excalidraw are unaffected (CC PR titles + squash, but no release-please), and verified setups combining PR-title linting with release-please under squash merge (googleapis org, npm template-oss, absinthe), including the lessons on pinning squash presets as code and the BLANK vs PR_BODY body preset trade-off. Link the report from ADR-010. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…n report Document how squash-merge setups preserve (or lose) BREAKING CHANGE footer details in changelogs: Google's title-only practice, npm's PR_BODY preset carrying footers into squash bodies (verified end-to-end against npm/cli d36945d and its v12.0.0 changelog), the BLANK-preset merge-dialog escape hatch with BEGIN_COMMIT_OVERRIDE as the retroactive fix, and npm/cli#9838's documented omission-and-recovery case. Note the hidden advantage of this repository's plain-merge strategy: branch commits' footers survive unchanged. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…port release-please extracts the override with a naive substring split on the merged PR body, so a prose mention of the literal marker arms the mechanism, a missing end marker captures the rest of the body, and the extracted text silently replaces the messages of every commit associated with the PR. Record the pitfall, the plain-merge fallback nuance, and the rule of thumb: never spell the marker in a PR body. Discovered first-hand on this report's own pull request (body since reworded). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
twada
added a commit
that referenced
this pull request
Aug 27, 2026
## Summary
Record the 2026-08-27 decision in the investigation report: this
repository transitions gradually from plain merge commits to squash
merge, with the squash presets set to PR_TITLE for the subject and
PR_BODY ("Pull request title and description") for the body.
## Motivation
With a blank squash body, the detailed rationale of a change lives only
in the pull request — a proprietary silo — and leaving GitHub would lose
it. With PR_BODY, the PR description, written to the same quality bar as
a commit message, becomes the squash commit body and persists in git
itself. This follows npm's configuration, verified end-to-end in the
report's ecosystem survey 3.
## Changes
The "Implications for this repository" section of the investigation
report now records: the chosen presets and their rationale; the
operating rules that follow (BREAKING CHANGE footers and deliberate
multi-unit paragraphs ride the PR description into the changelog, while
unintentional bare Conventional Commits paragraphs and the literal
commit-override marker remain the two pitfalls); and the underlying
model — the atomic, revertable unit of history is the squashed PR, with
PRs shrinking toward single-intent changes and behavior/structure
changes separated at the PR level in the tidy-first sense.
## References
-
docs/investigations/2026-08-27-release-please-changelog-duplication-research.en.md
(the updated file)
- PR #47 — the trial squash merge that started this discussion
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
RELEASING.md and ADR-010 previously described the duplicate-changelog-entry problem as having unclear trigger conditions ("the trigger conditions are not fully understood, so check every release"). Research into release-please's implementation and issue tracker shows the behavior is deterministic, so this PR replaces the hedged wording with the identified conditions and records the full research as an investigation report.
Findings
splitMessages()insrc/commit.ts) deliberately splits a commit's message body on paragraph-leading Conventional Commits lines and treats each as a separate commit. There is no option to disable this, and the upstream report (Merge Commits leading to Duplicate Changelog Entries googleapis/release-please#2476) was closed as not planned.fix:/feat:),chore:/ci:/docs:), and PR fix(runtime): filter out Node.js v24.9.0 generated assertion messages #26 predates release-please's scan range (released manually as runtime 0.3.1).Changes
docs/investigations/2026-08-27-release-please-changelog-duplication-research.en.md: the full analysis (split-regex subtleties, why Electron/Vite/Excalidraw are unaffected, verified setups combining PR-title linting + release-please + squash merge in the googleapis org, npm template-oss, and absinthe, and the lessons on pinning squash presets as code and the BLANK vs PR_BODY trade-off, plus how squash setups preserve BREAKING CHANGE footer details — title-only vs PR_BODY-carried footers vs merge-dialog editing with the commit-override markers as the retroactive fix)🤖 Generated with Claude Code