Skip to content

Collect changelog lines from per-PR fragments - #2038

Merged
benalleng merged 1 commit into
payjoin:masterfrom
DanGould:changelog-fragments
Nov 9, 2026
Merged

benalleng merged 1 commit into
payjoin:masterfrom
DanGould:changelog-fragments

Conversation

@DanGould

@DanGould DanGould commented Nov 7, 2026 •

Copy link
Copy Markdown
Member

We keep getting merge conflicts in CHANGELOG.md because every PR adds its line under the same ## Unreleased heading. This does what Bitcoin Core does with doc/release-notes-*.md. Each PR adds its own file instead. We @xstoicunicornx @benalleng @spacebear21 discussed this offline, which is why I did not create a new issue.

A PR that changes what users of a crate see adds a uniquely named Markdown file to that crate's changelog.d/ directory, for example payjoin/changelog.d/reject-duplicate-inputs.md. The file holds list items, optionally under a ### heading like ### API Additions. Language-specific binding changes go in payjoin-ffi/<language>/changelog.d/. CONTRIBUTING.md has the details.

bump.sh builds the new version's section from the fragments and deletes them. Items that share a ### heading are grouped under it. The changelog check now asks for a fragment instead of a CHANGELOG.md edit, and it rejects a fragment bump.sh can't read. A bump PR passes the check by deleting the fragments it moves.

If a PR merges while the bump PR is open, rebase the bump branch and run bump.sh again at the same version. It moves the new fragments into the existing section and keeps the text that's already there. check-invariants.sh now fails while the released crate still has fragments, so tag.sh won't tag a release whose notes are missing a change.

The current Unreleased entries are moved into fragments, one per change.

Tested by bumping payjoin to 1.3.0 and payjoin-ffi to 0.26.0 in a scratch clone, including a fold after late fragments, a section with release prose on top, and refusals for an empty or malformed fragment. The changelog check's two steps were run by hand against fake PRs.

Reviewer: @spacebear21

Disclosure: co-authored by Claude Code. red teamed with codex to validate the behavior and fixed some holes.

@DanGould
DanGould requested a review from spacebear21 November 7, 2026 06:50
@DanGould
DanGould force-pushed the changelog-fragments branch from e37c422 to 8d16258 Compare November 7, 2026 07:17
@coveralls

coveralls commented Nov 7, 2026 •

Copy link
Copy Markdown
Collaborator

Coverage Report for CI Build 42414560845

Coverage remained the same at 87.844%

Details

  • Coverage remained the same as the base build.
  • Patch coverage: No coverable lines changed in this PR.
  • No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.


Coverage Stats

Coverage Status
Relevant Lines: 18616
Covered Lines: 16353
Line Coverage: 87.84%
Coverage Strength: 313.96 hits per line

💛 - Coveralls

Every pull request that changes a release crate adds its line under the
same "## Unreleased" heading, so any two open pull requests for a crate
conflict in CHANGELOG.md, and each merge forces a rebase on the rest.

Do what Bitcoin Core does with doc/release-notes-*.md. A pull request
adds its own uniquely named file under <crate>/changelog.d/, and bump.sh
moves the fragments into the new version's section and deletes them.
contrib/release/changelog-fragments.sh assembles the section: list items
outside a heading first, then each "### " heading with the items every
fragment puts under it. It rejects prose and "## " headings, which would
end the version's section early, continuation lines that prettier would
lift out of their item, and anything in changelog.d/ that is not a
visible, regular .md file with LF line endings, since bump.sh deletes
what it reads and check-invariants counts what is left. The changelog
check runs it on every directory bump.sh reads, rejects tracked files in
any other changelog.d/, and now asks for an added, changed or renamed
fragment instead of a CHANGELOG.md edit. A deleted fragment counts only
when the crate's [package] version changes too, which is what a bump PR
does. version_at, which reads that version at a git ref, moves to
crates.sh for this, and now parses the [package] table instead of
taking the first line-anchored "version", so check-bump.sh shares it.

bump.sh checks the fragments before it edits anything, refuses untracked
files in the directories it reads, and refuses to bump a release crate
that has none, since extract-changelog.sh cannot fill a release body
from an empty section. The language changelogs read
fragments from payjoin-ffi/<language>/changelog.d/ the same way.

A pull request can merge while a bump PR is open, or after it and before
the tag. When run again at the version a bump already set, bump.sh moves
the new fragments into that version's section, keeping the text already
there, and fills in new placeholders. check-invariants fails while the
released crate's changelog.d/ still holds a fragment, so tag.sh and the
bump PR check refuse a release whose notes miss a change it ships.

The existing Unreleased entries move into fragments, one per change.

Keep blank lines within items so folding preserves paragraphs and code.
Let FFI source changes use any supported language fragment directory,
and read Git paths without display quoting so unusual names count.
Document the fragment syntax and direct C# changes to the shared FFI
changelog directory.

Co-authored-by: spacebear <144076611+spacebear21@users.noreply.github.com>

@spacebear21 spacebear21 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ACK - I folded some bot-suggested fixes into 93af8e0:

Keep blank lines within items so folding preserves paragraphs and code.
Let FFI source changes use any supported language fragment directory,
and read Git paths without display quoting so unusual names count.
Document the fragment syntax and direct C# changes to the shared FFI
changelog directory.

@DanGould
DanGould requested a review from benalleng November 9, 2026 15:35
@DanGould

DanGould commented Nov 9, 2026

Copy link
Copy Markdown
Member Author

Need external review to merge. Not sure if this was actually broken before 93af8e0 or if it could have been a follow up vs stalling for the weekend?

@benalleng benalleng left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ACK 93af8e0

The CONTRIBUTING.md I think is still confusing but I don't have any actionable tweaks to make it better. maybe I just need to sit on it some more.

@benalleng
benalleng merged commit c02e4a8 into payjoin:master Nov 9, 2026
37 checks passed
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.

4 participants