aio-libs / multidict / 36228053380

87%

push

github

Render changelog roles as Markdown in GitHub Release notes (#1596)

<!-- Thank you for your contribution! -->

## What do these changes do?

The release workflow publishes the `CHANGES.rst` section verbatim as the
GitHub Release body, which GitHub renders as Markdown. Headings, lists,
emphasis and double-backtick literals already display correctly there,
but every Sphinx role (`:class:`, `:meth:`, `:exc:`, `:user:`, `:doc:`
and so on) shows up as raw text; see the v6.9.1 release page.

A new `tools/release_notes_md.py` rewrites the roles before
`create-release` reads the file: code references become code spans
(`:meth:`~multidict.MultiDict.getall`` becomes `` `getall()` ``,
matching what Sphinx renders), `:user:` becomes a profile link rather
than a bare `@handle`, so contributors are not pinged, `:doc:` links to
the page on multidict.aio-libs.org, and `:issue:`/`:pr:` become `#N`.
The deploy job checks out the sdist, so the script is added to
`MANIFEST.in`. `CHANGES.rst` and the docs are unchanged.

## Are there changes in behavior for the user?

No; only the GitHub Release page renders differently.

## Is it a substantial burden for the maintainers to support this?

No. It is a 60-line script with its own tests, and it only runs in the
deploy job.

## Related issue number

N/A

## Checklist

- [x] I think the code is well written
- [x] Unit tests for the changes exist
- [x] Documentation reflects the changes (N/A, CI only)
- [ ] If you provide code modification, please add yourself to
`CONTRIBUTORS.txt` (N/A)
- [x] Add a new news fragment into the `CHANGES/` folder
- [x] `make doc-spelling` passes and any new technical words are added
to `docs/spelling_wordlist.txt`

Drafted with Claude Code (Claude Opus 5.5); pending review by @asvetlov
before leaving draft.

<details>
<summary>Agent run details (optional, for reviewers)</summary>

Tests: `tests/test_release_notes_md.py`, 19 passed, 100% line and branch
coverage of the script and the test file.
End... (continued)

781 of 1562 branches covered (50.0%)

Branch coverage included in aggregate %.

45 of 46 new or added lines in 1 file covered. (97.83%)

8213 of 8763 relevant lines covered (93.72%)

1.87 hits per line