The changelog merges by union, so a sibling merge no longer costs a hand-resolved rebase

[MarkusNeusinger]

What

.gitattributes declares CHANGELOG.md merge=union. Two PRs that each add bullets under [Unreleased] no longer conflict: git keeps both sides (ours first, then theirs) instead of raising a conflict, so a rebase onto main goes through untouched.

The one thing union cannot judge is a line that BOTH sides changed — it would appear twice. The rule that keeps union safe therefore stands in three places (the file's header, CLAUDE.md, .github/copilot-instructions.md): add a new bullet on top of its category, never rewrite existing lines in passing.

Why

Every merge of one open PR turned the others DIRTY on CHANGELOG.md — four hand-resolved rebases on 2026-08-30 alone — and a DIRTY PR gets no CI run at all (GitHub cannot build the merge commit). Owner's ask: „könnten wir das irgendwie selbstheilen machen".

Verified

With the same attribute set locally (.git/info/attributes) the rebases of #458 and #459 onto main after the #457 merge went through with zero conflicts; the resulting [Unreleased] holds every bullet exactly once (checked by count), gates green on both.

Open question — one thing this cannot promise

Whether GitHub's own mergeability check honours merge=union (it applies its own merge when computing DIRTY/CLEAN; built-in drivers may or may not be respected). If it does, sibling PRs simply stay CLEAN after a merge. If it does not, the PR still shows a conflict in the UI, but the local rebase is one command and needs no hands — still self-healing from our side. The next sibling merge will tell; if GitHub ignores it, the robust next step is changelog fragments (changelog.d/<pr>.md, assembled at release time), which touch no shared file at all.

[Copilot]

🟡 Changes recommended

Multiple docs currently state “never conflict / no longer conflict” as an absolute, but union merges can still duplicate lines and may not be honored by GitHub’s mergeability check, so the wording should be softened to avoid a misleading guarantee.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR configures Git’s built-in merge=union driver for CHANGELOG.md to reduce churn and manual conflict resolution when multiple PRs add [Unreleased] entries, and documents the accompanying “add-only” rule across the repo’s contributor guidance.

Changes:

• Add CHANGELOG.md merge=union to .gitattributes to make concurrent changelog bullet additions merge without conflicts in local Git merges/rebases.
• Document the “add on top, don’t rewrite existing lines” rule in CHANGELOG.md, CLAUDE.md, and .github/copilot-instructions.md.
• Add a [Unreleased] changelog entry describing the change.

File summaries

File	Description
.gitattributes	Declares CHANGELOG.md merge=union and explains the safe-usage rule.
CHANGELOG.md	Documents the union-merge behavior and adds an [Unreleased] entry about the change.
CLAUDE.md	Updates contributor guardrails to mention the union merge behavior and the add-only rule.
.github/copilot-instructions.md	Mirrors the guardrail update for Copilot-driven contributions.

Review details

Suppressed comments (1)

CHANGELOG.md:32

• This changelog entry claims sibling PRs "no longer conflict" and that rebases go through "untouched". Union merges can still yield duplicated lines (and GitHub’s DIRTY/CLEAN check may not apply the driver), so the entry should describe this as a conflict-reduction measure for local merges/rebases rather than a guaranteed end to conflicts.

- **The changelog merges by union — sibling PRs no longer conflict in it.**
  Every merge of one open PR used to turn the others `DIRTY` on
  `CHANGELOG.md` (four rebases with hand-resolved conflicts on 2026-08-30
  alone), and a DIRTY PR gets no CI run. `.gitattributes` now declares
  `CHANGELOG.md merge=union`: git keeps both sides' bullets instead of

• Files reviewed: 4/4 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[MarkusNeusinger]

Agreed — reworded in one voice across the header, the entry, CLAUDE.md and copilot-instructions.md (and the PR title): a local merge or rebase resolves itself, GitHub's own mergeability check may still flag the PR until the rebase lands, and a line changed on both sides appears twice — hence the add-on-top rule.

[Copilot]

🟢 Approval recommended

The change is a small, well-scoped Git attribute/workflow documentation update with no functional runtime impact and consistent documentation updates across the repo.

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 0 new
• Review effort level: Lite