docs: add CHANGELOG.md (back to v8.7.1) and auto-update it on release

[twcclegg]

Changes

• Add CHANGELOG.md at the repo root, populated retroactively from v8.7.1 through the current v9.0.38, built from tag history, GitHub Release notes, and merged PR titles.
• Update lib/github-actions-metadata-update.sh to append a new CHANGELOG.md entry for each future release, in the same commit as the metadata sync.
• Mention the changelog in README.md's intro and "Metadata updates" section.

Retroactive changelog

212 tags exist between v8.7.1 (2017) and today. Rather than 212 near-identical headers, consecutive metadata-only releases are condensed into ranged entries (e.g. ## [v8.11.4 – v8.12.34] - 2020-02-13 – 2021-10-07, "35 metadata-only releases..."), while releases with an actual code change get their own entry with real detail — the net35/net6.0/net8.0/net9.0/net10.0 target additions and removals, the ShortNumberUtil and PhoneNumberToTimeZonesMapper additions, the libphonenumber-csharp.extensions package and its System.Text.Json converter and (most recently) TryParse/TypeConverter/ValidationAttribute additions, several real bug fixes (leading zeroes, a + being stripped, MX area codes, a null-ref in normalization), the perf work in 2023 ("reduce regex abuse", skip internal builders, stackalloc Format()), the binary-metadata build pipeline, the strong-naming saga in v9.0.0/v9.0.1 (added, then reverted the very next release), and this release's own rework of the metadata-sync automation. Every version number still gets a matching entry — none are silently skipped, they're just grouped where nothing happened.

Content came from git tag/git log, list_releases/get_release_by_tag, and list_commits/search_pull_requests for the PRs behind each interesting-looking commit message — not invented.

Where the automation lives, and why

The task suggested two options: update the changelog in the metadata-update PR itself, or have finalize_metadata_release.yml add it once the release/tag actually exists. I went with the former:

• The version number isn't actually a guess. github-actions-metadata-update.sh names its branch metadata-update/vX.Y.Z and commits feat: automatic upgrade to vX.Y.Z before opening the PR — UPSTREAM_GITHUB_RELEASE_TAG is already the exact version this port will publish under, copied verbatim from the upstream tag being synced (this port tracks upstream's version number 1:1). There's nothing to wait for.
• finalize_metadata_release.yml can't push a follow-up commit anyway. It only tags an existing commit and calls the Releases API — per its own comments and github-actions-metadata-update.sh's file-level comment, main's branch-protection ruleset requires a PR + passing checks for every push, with no bypass for any actor, including this automation's own libphonenumber-csharp-bot PAT (that's the documented reason the metadata sync itself moved from a direct push to a PR). A direct push of a changelog commit from the finalize step would hit the exact same wall the metadata sync used to. I couldn't query the ruleset directly via the API in this sandbox (GitHub App access for that call isn't enabled here), so I relied on the two workflows' own comments, which state this as settled fact already — finalize_metadata_release.yml's only non-tag/release/dispatch action is calling POST /releases, which creates a tag ref rather than writing refs/heads/main, so it sidesteps the ruleset rather than needing an exemption from it.
• Doing it in the metadata-update PR keeps everything in the one PR that already goes through checks + auto-merge — no second PR-and-review cycle per release, and no new permissions needed.

The entry itself is intentionally terse for the common case (a one-line "Metadata update to upstream vX.Y.Z" with a compare link) — anything worth more than that is something a human would want to word by hand anyway, and can still edit the PR before it auto-merges.

Testing

• bash -n lib/github-actions-metadata-update.sh — syntax check.
• shellcheck lib/github-actions-metadata-update.sh — no new findings (both pre-existing warnings are unrelated to this change).
• Unit-tested the sed-based insertion logic standalone against a copy of the real CHANGELOG.md, including two insertions back-to-back, to confirm new entries land immediately below the <!-- next-entry --> marker and stay in reverse-chronological order.
• Ran UPSTREAM_TAG=v9.0.33 DEPLOYED_VERSION=9.0.32 bash lib/github-actions-metadata-update.sh --dry-run to confirm the rest of the script's flow is unaffected (it exits before reaching the new code, same as before, since the sandbox can't reach the GitHub API to go further).
• No C# code touched, so dotnet build/dotnet test weren't re-run for this change.

---

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.33%. Comparing base (0bf7478) to head (71fdb57).
⚠️ Report is 18 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #441      +/-   ##
==========================================
+ Coverage   87.26%   87.33%   +0.07%     
==========================================
  Files          41       43       +2     
  Lines        3831     3885      +54     
  Branches      978      991      +13     
==========================================
+ Hits         3343     3393      +50     
- Misses        284      287       +3     
- Partials      204      205       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.