CI: make changelog automation LLM-based (Gemini) and race-safe

[Gui-FernandesBR]

Problem

The post-merge Populate Changelog job (.github/workflows/changelog.yml) used a blind label→prefix mapping inline in the workflow. It:

• Double-prefixed titles that already carried a conventional prefix — e.g. PR BUG/MNT: pre-release v1.13.0 review fixes #1074 (BUG/MNT: ...) landed as ENH: BUG/MNT: pre-release v1.13.0 review fixes (still visible in the v1.13.0 section).
• Never deduplicated — a re-run inserted the same entry twice.
• Only ever used Added / Changed / Fixed, never Deprecated / Removed / Security.
• Pushed without a rebase, so it lost races against concurrent merges into develop (the "sometimes it just doesn't work").

What changed

.github/scripts/update_changelog.py — the entry is now formatted and placed by Gemini (model alias gemini-flash-latest), behind a deterministic safety net:

• Only the [Unreleased] block is ever rewritten; released history is preserved byte-for-byte.
• Model output is validated before use: every existing [#N](url) link must survive, the new PR must be referenced exactly once, no released ## [vX] header may leak in, and growth is bounded.
• On any failure — API error, rejected output, or missing GEMINI_API_KEY — it falls back to a safe deterministic insert that detects an existing prefix (never producing ENH: BUG: ...) and skips duplicates.
• Idempotent: a PR already referenced in [Unreleased] is a no-op.

changelog.yml — installs google-genai, passes PR_BODY + GEMINI_API_KEY, and the push step now rebases and retries (5×) to survive concurrent merges.

.github/scripts/test_update_changelog.py — 13 self-contained tests of the deterministic pieces (split/reassemble, dedup, anti-double-prefix, canonical section ordering, output validator). They run without network or the google-genai package. ruff check and ruff format --check are clean.

Docs — docs/development/first_pr.rst, docs/development/style_guide.rst, and .github/pull_request_template.md now state that contributors do not edit CHANGELOG.md: the LLM writes the entry after merge, so you just open and merge PRs.

⚠️ Action required: add the GEMINI_API_KEY repository secret

Before this workflow can use Gemini, a maintainer must add the API key as a repository secret:

Settings → Secrets and variables → Actions → New repository secret — name GEMINI_API_KEY.

Without it the job still runs via the deterministic fallback (no LLM). The key is only ever read from secrets.GEMINI_API_KEY; it is never hardcoded or logged.

Notes

• Model choice: gemini-2.5-flash is now blocked for new API keys (returns 404 "no longer available to new users"), so the alias gemini-flash-latest is used to track the newest stable flash model and avoid future breakage.
• The stray ENH: BUG/MNT: ... line already committed in the released v1.13.0 section is left untouched (released history); can be cleaned up separately if desired.
• If two PRs edit the top of the same subsection simultaneously, the rebase may conflict and the job fails loudly (::error::) rather than corrupting the file — manual fixup needed.

🤖 Generated with Claude Code

[Gui-FernandesBR]

⚠️ Action required: add the `GEMINI_API_KEY` repository secret

Before this workflow can use Gemini, a maintainer must add the API key as a repository secret:

Settings → Secrets and variables → Actions → New repository secret

• Name: `GEMINI_API_KEY`
• Value: (the Gemini API key)

Until the secret exists, the job still runs — it just falls back to the deterministic insert (no LLM). The key is only ever read from `secrets.GEMINI_API_KEY`, passed to the script as an env var; it is never hardcoded or printed to logs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.36%. Comparing base (e0ff281) to head (c524b92).
⚠️ Report is 13 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1082      +/-   ##
===========================================
+ Coverage    82.18%   82.36%   +0.18%     
===========================================
  Files          122      122              
  Lines        16355    16377      +22     
===========================================
+ Hits         13441    13489      +48     
+ Misses        2914     2888      -26     

☔ 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.