chore: replace changelog merge=union with changelog.d fragments

[alex-clickhouse]

Problem

The merge=union attributes on CHANGELOG.md / RELEASENOTES.md added in #489 don't work: GitHub ignores .gitattributes merge drivers when merging pull requests (github/community#9288), which is exactly where the conflicts happen.

It isn't the right answer locally either — union merge resolves by interleaving both sides' lines, so entries land under the wrong heading and can duplicate. It removed conflicts without producing correct output.

Approach

The fragment pattern, as used by towncrier (Python) and changesets (JS). Each change drops its own file in changelog.d/, so two PRs add two distinct paths and git has nothing to reconcile. No merge driver required.

dotnet run scripts/changelog.cs -- --new fixes 512-variant-null

scripts/changelog.cs is a .NET 10 file-based app — no dependencies, ~280 lines, 0.33s warm. It lives outside every project directory, so the solution build ignores it.

Command
--new <category> <name>	scaffold a fragment
--check	CI gate
--render	preview the pending Unreleased section
--release <version>	fold fragments in, regenerate notes, delete them
--sync-notes	regenerate RELEASENOTES.md

RELEASENOTES.md is now generated

The two files were byte-identical over their overlap apart from three drifted lines — RELEASENOTES.md was just CHANGELOG.md truncated at v1.0.0. So every PR was writing the same prose twice, doubling the conflict surface for no extra information.

CHANGELOG.md is now the single source of truth; RELEASENOTES.md is generated from it (it ships in the package via PackageReleaseNotes). CI fails if it drifts.

The two behave oppositely at release time: CHANGELOG is prepended to and never rewritten; RELEASENOTES is fully replaced, so sections fall off the bottom when ReleaseNotesFloor is bumped at a major.

Verification

Fragment bodies were extracted by line number, not retyped. The round-trip is proven: --release reproduces main's Unreleased section with zero prose lines changed — a sorted-line diff shows only the two added header lines.

That mattered for one non-obvious reason: the 158-line v1.0.0 section uses bare --- lines as horizontal rules, which a naive "line followed by ---" parser reads as phantom sections. The header rule also requires a version-shaped title; those rules survive --release intact.

Also covered: all four fragment-validation failures, unknown category, the double-apply guard, and the version floor (0 pre-1.0 sections in RELEASENOTES, 3 retained in CHANGELOG).

Reviewer notes

• Entries reorder. Sorting by PR number moves 7 improvement bullets within their section. Identical as a set; ordering is now deterministic instead of merge-order.
• The empty Unreleased stub is dropped from RELEASENOTES. Since --check keeps that section empty, the generated notes would otherwise ship a stub header inside the .nupkg. It now opens on the newest released version.
• One content change reaches the shipped notes. RELEASENOTES.md regains (see ClickHouse.Driver.Common/Vendor/K4os) on the LZ4 entry — the single place the two files intentionally diverged. Flagging it explicitly since it's a repo-internal path; say the word and I'll reword the CHANGELOG entry instead.
• Known gap: CI can't detect "behavioral change with no changelog entry" — a PR touching only source doesn't trip the path filter. Still a reviewer responsibility, which the updated review skill now asks about explicitly.

Docs updated in CONTRIBUTING.md, AGENTS.md, changelog.d/README.md, and both review-skill mirrors.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

This PR replaces the previously attempted merge=union approach for changelog conflict avoidance with a fragment-based workflow (changelog.d/), backed by a new scripts/changelog.cs tool and updated docs/review guidance. This fits the repo by making changelog updates conflict-free across concurrent PRs and by generating RELEASENOTES.md from CHANGELOG.md as a single source of truth.

Changes:

• Add scripts/changelog.cs to scaffold, validate, render, and release changelog.d/ fragments, and to generate/sync RELEASENOTES.md.
• Move existing “Unreleased” prose out of CHANGELOG.md / RELEASENOTES.md into per-change fragment files under changelog.d/.
• Update contributor/agent docs and review-skill checklists to require fragments and treat RELEASENOTES.md as generated.

Reviewed changes

Copilot reviewed 33 out of 33 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
scripts/changelog.cs	New tool to manage changelog fragments and generate release notes.
CHANGELOG.md	Removes “Unreleased” body so entries come only from fragments.
RELEASENOTES.md	Drops “Unreleased” stub; keeps release notes content generated from changelog.
changelog.d/README.md	Documents the fragment workflow and naming/categories.
changelog.d/496-getschema-columns-where-clause.fixes.md	Changelog fragment extracted from prior Unreleased entry.
changelog.d/495-getschema-columns-dispose-command.fixes.md	Changelog fragment extracted from prior Unreleased entry.
changelog.d/482-typed-array-reads.improvements.md	Changelog fragment extracted from prior Unreleased entry.
changelog.d/481-small-tuple-construction.improvements.md	Changelog fragment extracted from prior Unreleased entry.
changelog.d/480-presize-map-read-dictionary.improvements.md	Changelog fragment extracted from prior Unreleased entry.
changelog.d/477-midstream-exception-detection.fixes.md	Changelog fragment extracted from prior Unreleased entry.
changelog.d/474-insertoptions-copy-drops-options.fixes.md	Changelog fragment extracted from prior Unreleased entry.
changelog.d/457-request-uri-allocations.improvements.md	Changelog fragment extracted from prior Unreleased entry.
changelog.d/453-dynamic-type-singletons.improvements.md	Changelog fragment extracted from prior Unreleased entry.
changelog.d/451-pooled-response-read-buffer.improvements.md	Changelog fragment extracted from prior Unreleased entry.
changelog.d/448-fixed-size-read-allocations.improvements.md	Changelog fragment extracted from prior Unreleased entry.
changelog.d/446-schema-table-numeric-scale.fixes.md	Changelog fragment extracted from prior Unreleased entry.
changelog.d/444-insert-serializer-buffer.improvements.md	Changelog fragment extracted from prior Unreleased entry.
changelog.d/442-stream-insert-payload.improvements.md	Changelog fragment extracted from prior Unreleased entry.
changelog.d/442-memorystreammanager-obsolete.deprecations.md	Changelog fragment extracted from prior Unreleased entry.
changelog.d/441-empty-http-error-body.fixes.md	Changelog fragment extracted from prior Unreleased entry.
changelog.d/437-pooled-compressor-write-buffer.improvements.md	Changelog fragment extracted from prior Unreleased entry.
changelog.d/434-poco-insert-boxing.improvements.md	Changelog fragment extracted from prior Unreleased entry.
changelog.d/432-decimal-write-allocations.improvements.md	Changelog fragment extracted from prior Unreleased entry.
changelog.d/431-builtin-lz4-codec.features.md	Changelog fragment extracted from prior Unreleased entry.
changelog.d/427-pluggable-insert-compression.features.md	Changelog fragment extracted from prior Unreleased entry.
changelog.d/420-variant-write-type-lookup.improvements.md	Changelog fragment extracted from prior Unreleased entry.
changelog.d/392-useformdataparameters-connection-string.improvements.md	Changelog fragment extracted from prior Unreleased entry.
CONTRIBUTING.md	Adds contributor guidance for fragments and release workflow usage.
AGENTS.md	Updates agent guidance to use fragments and the new CI gate.
.gitattributes	Removes reliance on changelog merge drivers; documents fragment approach.
.github/workflows/changelog.yml	Adds CI validation/rendering for fragments and generated release notes.
.claude/skills/review/SKILL.md	Updates review checklist to require fragments and treat notes as generated.
.agents/skills/review/SKILL.md	Same review-checklist update (mirrored skill).