chore: union-merge CHANGELOG.md to stop parallel PRs conflicting - #319
Merged
Conversation
Every change adds a bullet to the same "Unreleased / Fixed" list, so any two open PRs conflict on CHANGELOG.md even when they touch nothing else in common. Across the five currently open fix PRs that accounted for four of the seven conflict resolutions needed to land them. The built-in union driver keeps both sides. Verified against the open PRs: merging #313 onto main with this in place drops its conflicts from {CHANGELOG.md, test_api.py} to {test_api.py}. Scope: git honours this for local merges and rebases. GitHub's web UI does not read .gitattributes merge drivers, so the merge button and the conflict banner are unchanged; the benefit is when resolving locally, which is how these PRs are being updated. Noted in the file so the next reader does not expect otherwise. Trade-off: if two branches genuinely edit the same CHANGELOG line, union keeps both versions instead of flagging it. For an append-only list that is a good trade. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
rddimon
approved these changes
Aug 24, 2026
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
2 participants
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.
Why
Every change adds a bullet to the same
Unreleased / Fixedlist, so any two open PRs conflict onCHANGELOG.mdeven when they touch nothing else in common.Across the five open fix PRs (#311, #312, #313, #317, #318) that accounted for four of the seven conflict resolutions needed to land them — more than the two real source conflicts combined. It is pure busywork: no two of those PRs ever edited the same CHANGELOG line.
What
One line, plus a comment explaining it:
unionis a built-in git merge driver, so nomerge.<driver>.driverconfig is needed on anyone's machine.Scope — please read before expecting too much
Git honours this for local merges and rebases. GitHub's web UI does not read
.gitattributesmerge drivers, so:The benefit lands when a branch is updated locally and pushed, which is how the open PRs are being brought up to date. This limitation is noted in the file itself so the next reader is not misled.
Trade-off
If two branches genuinely edit the same CHANGELOG line — say both reword an existing entry — union keeps both versions rather than flagging a conflict. For an append-only list of release notes that is a good trade, but it is a real behaviour change worth knowing about.
Test plan
Verified against a real open PR rather than a synthetic case. With this commit as the base, merging #313 drops its conflicts:
mainCHANGELOG.md,test/unit/test_api.pymain+ this changetest/unit/test_api.pyAlso exercised earlier across all five open PRs merged in sequence: all four CHANGELOG conflicts disappeared, and the resulting
Unreleasedsection contained every entry in merge order with no duplication and no leftover markers.No code paths touched; the full suite is unaffected.