Skip to content

Switch changelog to per-PR fragment files (avoid Pending-section conflicts) - #30

Closed
quinnmil wants to merge 1 commit into
mainfrom
changelog-fragments
Closed

quinnmil wants to merge 1 commit into
mainfrom
changelog-fragments

Conversation

@quinnmil

Copy link
Copy Markdown
Contributor

Summary

Every PR that needed a changelog entry edited CHANGELOG.md's ## Pending section directly. With more than one PR open at a time, they collided on the same handful of lines every time, and each merge forced the next open PR to redo the conflict resolution — we hit this repeatedly on the last batch of PRs.

Change

  • New changelog.d/ directory: each PR adds a new file here (e.g. changelog.d/42.md) with its own ### Added/### Changed/### Fixed/### Removed bullets, instead of editing CHANGELOG.md. Two PRs adding two different files can't conflict.
  • New scripts/assemble_changelog.py <version>: run at release time to fold every fragment into a new ## [X.Y.Z] - date section in CHANGELOG.md, in the usual Added/Changed/Fixed/Removed order, then delete the consumed fragments. Verified locally with dummy fragments — output matches the existing changelog formatting exactly.
  • Updated the /release process to run the script instead of hand-editing the Pending section (local-only change, not part of this diff — see note below).

No functional CLI changes; CHANGELOG.md itself is untouched by this PR.

Note

This repo's .claude/ directory isn't tracked in git yet, so the corresponding update to .claude/commands/release.md (the /release skill) only exists locally on this machine for now — happy to add .claude/ to the repo in a follow-up if you'd like the process docs to live here too.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BK3fzED9ksTWsvoPfsEwpS

Every open PR editing CHANGELOG.md's `## Pending` section directly meant
any two concurrent PRs collided on the same lines, and each merge forced
the next PR to redo the conflict resolution. Add changelog.d/, where each
PR drops a new file instead of editing the shared section, so concurrent
PRs can never conflict on this axis. scripts/assemble_changelog.py folds
the fragments into a versioned CHANGELOG.md section at release time.

See changelog.d/README.md for the fragment format and
.claude/commands/release.md for the updated release process (not
committed here — .claude/ isn't tracked in this repo yet).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BK3fzED9ksTWsvoPfsEwpS
@quinnmil

Copy link
Copy Markdown
Contributor Author

Reverting this in favor of plain direct edits to CHANGELOG.md's Pending section — decided the fragment-file system was more process/tooling than this repo's actual PR concurrency warrants. See conversation for the discussion; the occasional conflict is an acceptable tradeoff at this scale.

@quinnmil quinnmil closed this Sep 11, 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