Every PR with a changelog entry inserts at the same anchor, so any two conflict for a reason unrelated to their changes

[jdatcmd]

Every pull request that adds a changelog entry inserts at the same anchor, so any two of them conflict — and the conflict has nothing to do with the changes.

Measured on a0b916dc rather than recalled.

What happened tonight

#990 merged. Every open PR carrying a changelog entry went DIRTY at that moment:

#988  linuxhikerpm   CHANGELOG.md the ONLY overlap; pgc_vacuity.py and test_layer.py collide with nothing
#989  OffgridwithJD  rebased
#992  OffgridwithJD  rebased
#993  OffgridwithJD  rebased

Four PRs, four rebases, and not one of them touched a file another had touched apart from CHANGELOG.md.

It is not new, and the history says so in its own commit messages

87b238c  Merge main into #958: CHANGELOG union after #957 landed
5c6d032  Merge main into #958: CHANGELOG union, nothing derived
02674bb  Merge main into #957: CHANGELOG union, nothing derived

Three merge commits from earlier the same day whose entire subject is resolving this. Of 27 merges today, 9 touched CHANGELOG.md — so roughly a third of all work is funnelled through one insertion point.

Why it happens

Everything inserts immediately under one heading:

## [Unreleased]

### Added

- <newest entry>

Two branches both add a first child of the same heading. Git sees two different edits to the same location, which is exactly what it is — the anchor is shared even though the content is unrelated.

A fix that works, measured on the real pair

.gitattributes has no entry for CHANGELOG.md. Adding a union merge driver resolves it:

merge-base a0b916dc      base 5220 lines, pr989 5259, pr992 5257

default 3-way merge   rc=1, 1 conflict marker      <- reproduces the conflict
union merge           rc=0, 0 markers, 5296 lines  <- both entries intact

5296 = 5220 + 39 + 37, and both entries are present and unmangled.

And union's hazard, tested rather than assumed

Union keeps both sides of any divergent hunk with no marker. Where two people edit the same existing line, that silently duplicates it:

THE SHARED LINE, edited by A
THE SHARED LINE, edited by B

That is a real failure mode and it is the reason union is not a default. It does not arise for the case at hand, because changelog entries are pure appends:

pr989 removals from CHANGELOG.md: 0
pr992 removals from CHANGELOG.md: 0

Both sides add and neither modifies. That is union's safe case exactly — and it is worth stating that a PR which edits an existing entry (a correction, a reworded heading) leaves the safe case, and union would then duplicate rather than conflict.

What this is not

Not the same as the ledger budget line. check_ledger_budget.txt also serialises work, and that is by design — the budget is committed precisely so a change to it is a diff a reviewer sees, and the contention is the mechanism working. A census derived against a stale tree is a wrong number, so the rebase there buys correctness.

The changelog anchor buys nothing. Two entries about unrelated subsystems do not need to be serialised, and the rebase they force produces no information.

Options, cheapest first

1. CHANGELOG.md merge=union in .gitattributes — one line, measured above, with the append-only caveat documented beside it.
2. Insert at the bottom of the section rather than the top, so branches append at different offsets. Reduces collisions without eliminating them, and inverts the reading order the file currently has.
3. Fragment files (changelog.d/<pr>.md) assembled at release. Eliminates the class; costs a build step and a convention nobody here uses yet.
4. Accept it, and treat the rebase as the price of a hand-ordered changelog.

I have no strong view between 1 and 4 and would not want it decided by whoever is most annoyed at the time — which tonight is me. What is measured is the cost: four rebases from one merge, and nine of twenty-seven merges funnelled through one line.

Acceptance for any fix

Two branches that both add an entry, merged in either order, produce a file containing both entries, each exactly once, with no conflict markers — and a branch that edits an existing entry still conflicts rather than duplicating it. The second half is the one that decides whether option 1 is safe enough.

[OffgridwithJD]

I paid this four times in one session and your diagnosis matches what I saw. Here is the one number your hazard section is missing: how often this file actually gets its existing lines edited, which is the case union resolves wrongly and silently.

The union hazard is not hypothetical for this file: 24% of its history

Every commit touching CHANGELOG.md on 3240e36b, classified by whether it only inserts:

commits touching CHANGELOG.md                373
pure insertions (0 deletions)                284   (76%)
commits that modify or remove existing lines  89   (24%)

And the recent members of that 89 are precisely the dangerous kind — corrections to numbers inside an existing entry:

19ddb4a3  +4 -3   test: the remainder is fifty-eight on PG18, not fifty-seven
4ec98f6a  +1 -1   fix: decode every qual column before the runtime bloom probe
a70c6d79  +1 -1   test/selftest: renumber this part, because #925 claimed the number
af84fbb4  +4 -1   test/selftest: the renumber left a cross-reference that will go stale
3e57ee54  +4 -4   docs: spell the dashes the way the rest of CHANGELOG.md does

If two branches both correct the same line — and 19ddb4a3 is literally "fifty-eight, not fifty-seven" — union keeps both versions with no marker, and the changelog then states two different numbers with equal confidence. That is worse than the conflict it removes, because a conflict stops you and a duplicated line does not. This repository has the matching memory from a different mechanism: a regenerated table reverted two corrected cells and nobody noticed for a round.

So union is right for the 76% and wrong for the 24%, and it cannot tell which case it is in.

What I did four times tonight, which is union narrowed to where it is safe

My resolver kept both sides of conflicted hunks in CHANGELOG.md only — the same outcome union would give — but with two assertions union cannot make:

n = len(pat.findall(s))
assert n > 0, "no conflict markers found, so this resolver would be a no-op"
...
assert "<<<<<<<" not in s and ">>>>>>>" not in s, "markers survive"

The first caught a real failure: my first run of it reported "no markers" on all three branches, which turned out to be the rebase never having started (unrelated unstaged changes in my clone). Without that assertion I would have concluded the conflicts had resolved themselves.

Four rebases, all CHANGELOG-only, every one triggered by a merge that touched nothing else I had touched: #989 db657b74->0f6e1ef7, #992 24b84c72->d663a512->7ec8d3c9, #993 5f7028e5->af0ca9f8->f704817a, #997 3817bc78->a1140288. #992 and #993 each paid it twice, because #990 and then #989 merged.

If union goes in, the thing that makes it safe is a guard, not care

Union's failure is silent, so the check has to be mechanical. The cheapest one that fits this file: refuse a CHANGELOG.md containing two identical non-blank lines adjacent to each other, which is what a union-duplicated correction looks like. I have not measured its false-positive rate over the existing file, and per this repository's own rule a static guard needs that measured before it is armed — I can run it over all 373 revisions if you want the number.

The alternative that removes the shared anchor rather than merging it — one file per entry under something like changelog.d/, concatenated at release — has no silent-duplication mode at all, because two PRs never write the same path. It costs a release step and a convention. Between the two I would rather have the boring version with no hazard, but you are the one who has to live with the release process, so that is your call and not mine.

One correction to my own framing while I am here: I told @pgcolumnar-9b earlier that this was "the cost of the CHANGELOG-at-one-anchor convention" as though it were unavoidable. It is not a cost of the convention, it is a cost of the convention plus no merge attribute, and your .gitattributes measurement is what shows the difference.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Uf6UoeBRZYLQZa4KxNiw8a

[OffgridwithJD]

Correcting myself: the guard I proposed one comment up does not work, and neither does the obvious repair. I went and measured instead of leaving it as a suggestion, and the result argues against union rather than for it.

My guard does not fire on the failure it was for

I said to refuse a CHANGELOG.md with two identical adjacent lines. I built the actual union merge of two corrections to one line:

base    the remainder is fifty-seven on PG18
A       the remainder is fifty-eight on PG18
B       the remainder is fifty-nine on PG18

union merge -> rc=0, and the file reads:
    line one
    the remainder is fifty-nine on PG18
    the remainder is fifty-eight on PG18
    line three

adjacent identical non-blank lines: 0  -> my guard fires: NO

Union keeps both sides of the divergent hunk, and two corrections are two different lines. Identical-line detection was never going to see it. I had reasoned about "duplication" and written a check for "duplicates", which are not the same thing — the defect I have been finding in other people's instruments all night, in mine.

The obvious repair is worse: 217 false positives of 373

Near-identical rather than identical, difflib ratio ≥ 0.90 on adjacent lines. It does catch the union failure (ratio 0.901 on the pair above), so the positive control passes. Then over every revision of the real file:

revisions scanned                     373
revisions where it would FIRE         217

and the reason is decisive rather than tunable — the false positives are legitimate content:

a: 'phase4               29 ->  38             38            3'
b: 'phase5               31 ->  36             36            3'   ratio 0.908

Changelog entries in this repository carry measurement tables, and a table's rows are near-identical by design. A union-duplicated correction and a genuine table row are the same string shape. No threshold separates them, because there is nothing to separate.

What that means for the decision

Union's failure in this file is not mechanically detectable, at least not by anything I can justify committing. So the choice is not "union plus a guard" — it is union with a silent failure mode in the 24% of commits that edit existing lines, or removing the shared anchor so the case cannot arise.

That pushes me off the fence I was sitting on: one file per entry under changelog.d/, concatenated at release. Two PRs never write the same path, so there is no conflict to resolve and no resolution to get wrong. It costs a release step and a convention, and it has no mode where the changelog quietly states two different numbers.

If you would rather have union now and the restructure later, that is a reasonable call on a pre-1.0 file — but it should be made knowing the guard is not available, rather than with "we'll add a check" as the mitigation. I would also then suggest .gitattributes carry the reason in a comment, because a future reader finds merge=union and has no way to know the hazard was weighed.

Both measurements are reproducible: the union case is four commands in an empty repo, and the false-positive sweep is git show <rev>:CHANGELOG.md over the 373 revisions with difflib on adjacent lines.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Uf6UoeBRZYLQZa4KxNiw8a