Aller au contenu
login
arrow_backRetour aux issues
MakazhanAlpamys/Soup #487

Every merge conflicts every open PR on CHANGELOG.md, because entries are inserted at the top of [Unreleased]

ecoDébutant enhancement help wanted

descriptionDescription

Observed three times in one afternoon: #479 merged and flipped #481 and #482 from `MERGEABLE/CLEAN` to `CONFLICTING/DIRTY`; I resolved both by hand; #481 then merged and conflicted #482 again on the same lines. None of it was a contributor error, and none of it was a real content disagreement. ## Mechanism Every PR adds its entry at the **top** of `## [Unreleased]` / `### Added`. Two PRs that touch entirely unrelated subsystems therefore edit the same line range, and git has no way to know both entries should simply coexist. The resolution is always identical: keep both, in either order. So the conflict rate is a function of *how many PRs are open*, not of whether they overlap. With 7 open PRs, one merge can conflict six of them — and each contributor then has to rebase for a reason that has nothing to do with their change. ## Why it is worth fixing rather than absorbing - It punishes contributors for someone else's merge, which is exactly the kind of friction that makes a first-time contributor give up. - It makes `MERGEABLE/CLEAN` meaningless as a queue signal — everything downstream of the next merge is about to be dirty. - The maintainer either resolves it by hand (I did, twice, and the second was undone within the hour) or pushes the cost onto people who did nothing wrong. - It costs a CI re-run each time, and every push from a first-time contributor needs manual approval, so it also costs maintainer attention. ## Options 1. **Append to the end of each `###` subsection instead of the top.** Smallest possible change, no tooling. Two PRs still collide if both append, but the conflict window is one line rather than a shared block, and git resolves many of them automatically. 2. **A `.gitattributes` union merge driver for `CHANGELOG.md`** (`CHANGELOG.md merge=union`). Git keeps both sides automatically. Cheap, and the failure mode is a duplicated line rather than lost content — but it can interleave two entries mid-paragraph, and this project's entries are long multi-paragraph prose, so this needs testing before adoption. 3. **Changelog fragments** (`changelog.d/.md`, assembled at release). Eliminates the conflict entirely because each PR writes its own file. Costs a release-time assembly step and a docs change; towncrier is the usual tool. I lean toward **1 first** (zero infrastructure, immediate relief) and evaluating **3** at the next release, where the assembly step is already a manual pass. **2** is tempting but the union driver's behaviour on this file's long entries should be demonstrated on a real pair of conflicting PRs before it is trusted. ## Acceptance - [ ] A decision recorded in `CONTRIBUTING.md` so contributors know where to put a new entry - [ ] If option 1: `.claude/CLAUDE.md`'s release checklist updated to match, since it currently describes editing `[Unreleased]` without specifying position - [ ] Demonstrated on two branches that both add an entry, showing the conflict is gone or reduced to a single auto-resolvable line - [ ] If option 2 or 3: the mechanism is documented in `CONTRIBUTING.md` and does not silently drop an entry when two PRs land in the same release Not urgent, and no code changes to `src/`. Good task for someone who wants to improve the contribution experience rather than the tool itself.
codeOuvre sur GitHub