Reconcile CHANGELOG.md vs GitHub release notes (single source of truth?)

[ChrisonSimtian]

Problem

The repo keeps two parallel records of what changes per release:

1. CHANGELOG.md — manually curated. PRs add an entry under [Unreleased] — <next-major> per the PR-creation flow in docs/agents/release-and-versioning.md. Reviewer-enforced.
2. GitHub release notes — generated on each release tag. Per CHANGELOG entry feat(release): generate rich release notes from milestone + auto PR list #21 ("Rich release notes from milestone + auto PR list"), the release body links the matching vX.Y.Z milestone and inlines the PR list.

They overlap. Sometimes they duplicate (fine). Sometimes they diverge (bad — CHANGELOG has hand-written prose; releases have flat PR titles). Neither is unambiguously canonical, and contributors aren't sure where to put what.

Open questions

1. Single source of truth — which one?
   • A: CHANGELOG.md canonical. Releases render the section verbatim or link to it. Pros: prose-first, human-curated, lives with the code, works offline. Cons: manual upkeep, easy to forget.
   • B: GitHub releases canonical. CHANGELOG.md generated (release-please / git-cliff / custom script from PR titles + labels). Pros: zero manual entry, conventional-commit-driven, one-button release. Cons: prose becomes mechanical.
   • C: Both, different audiences. CHANGELOG = developer-facing detail + migration paths; releases = user-facing announcement + highlights. Pros: each serves its purpose. Cons: doubles maintenance.
2. Conventional commits + auto-generation. History already follows conventional commits (feat, fix, chore, docs, test, !). Most of the way to auto-generated notes. Tools to evaluate: release-please-action (version bumps + CHANGELOG), git-cliff (flexible templates), gh release --generate-notes (built-in, simpler).
3. version.json (Nerdbank.GitVersioning) interaction. Whatever we pick must play with NB.GV's commit-height versioning. Auto-bump tools that rewrite version.json must land the bump commit before NB.GV computes patch height; mid-release commits between bump and tag shift the version.
4. Breaking-change visibility. Today breaking changes go under ### Breaking changes at the top of CHANGELOG.md. gh release --generate-notes can auto-flag breaking-change-labelled PRs — but only with a .github/release.yml, which we don't have yet.
5. History — backfill? CHANGELOG.md has rich 10.x / 11.0 entries; GitHub releases for those tags are sparser. One-time alignment pass, or accept asymmetric history?

Suggested first step (not blocking discussion)

• Add .github/release.yml to at least categorise auto-generated notes by label (breaking-change, feat, fix, docs). Low-cost regardless of which option wins.
• Decide A/B/C, then file the implementation work.

Definition of done

• Pick A/B/C (or a documented hybrid).
• Document the decision in docs/agents/release-and-versioning.md.
• If B wins, file follow-ups for the generation tooling and CHANGELOG migration.

[dennisdoomen]

@ChrisonSimtian With #375, we went for B. Do you still see value in C? In FluentAssertions, we do C, but we're considering to drop that as everything is in the GH release notes already. And the PR explain the consequences of breaking changes. For bigger releases, there's always a migration page on the website. We could do something like that for Fallout as well.

[ChrisonSimtian]

B is fine, lets drop obsolete things. I think we can close this now that its migrated over to gh release