docs(changelog): summarise each release with a link to its full entry (#900)

[JarryShaw]

Please follow the guide below

• You will be asked some questions, please read them carefully and answer honestly

• Put an x into all the boxes [ ] relevant to your pull request (like that [x])

• Use Preview tab to see how your pull request will actually look like

• Searched for similar pull requests

• Followed the coding style (make pylint, make mypy, make isort) -- N/A, no Python changed

• make test passes, and a test case covers the change -- ran tests/project/test_changelog_md.py directly (47 tests / 37 subtests pass); the full suite OOMs and was not run

• Added a changelog entry under docs/source/changelog/ and regenerated CHANGELOG.md, if the change is user-visible -- N/A -- changelog centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657

What is the purpose of your pull request?

• docs — documentation only

---

Description of your pull request and other information

Closes #900. changelog.rst was a bare toctree -- a list of version links with no indication of what each release changed. Each of the 37 entries now gets a one- or two-line summary drawn from its own page under changelog/<version>.rst, followed by a :doc: link to the full entry.

The toctree itself moves to the bottom, gains :hidden:, and keeps the exact newest-first order util/changelog_md.py reads to pick the release CHANGELOG.md is generated from -- confirmed with --check (exit 0) and tests/project/test_changelog_md.py. No file under docs/source/changelog/ changes, and changelog.rst itself ships in neither the sdist nor CHANGELOG.md (MANIFEST.in prunes docs/), so nothing shipped moves.

[JarryShaw]

NEEDS CHANGES on ebf574d17 — cross-review (opus; author sonnet). The mechanics are sound and all five load-bearing claims verify. The verdict turns on prose: three summaries overstate their page, one with a demonstrably false number, and nothing tests the 37 new hand-maintained duplications.

The reviewer read all 37 pages, not the 8 I asked for. 34 are faithful, several verbatim. Three are not:

1. The 1.5.0 bullet is false, and it is the flagship. It says "across roughly 140 issues and pull requests between #326 and #509". Measured by me against the page's own body:

distinct #nnn refs total   : 137
distinct refs in [326,509] :  89
distinct refs outside      :  48
min, max                   : 251, 638

#251 sits below the range and 47 refs sit above it, several being real bullets — #514 (opt-in subclass registration), #630/#631 (packaging). The author did not invent this: it is copied near-verbatim from docs/source/changelog/1.5.0.rst:7-8, so the root defect is #657's, not #909's judgement. But #909 promotes it to the page a reader lands on first, making two copies to fix. Cheapest fix here: drop the count and range from the index bullet entirely — that detail belongs on the page, not in a one-line summary. Raised separately on #657.

2. 1.3.5 — "silently" is the author's own word and the page contradicts it. The page says the frames were "reported as raw, typically with 'int' object has no attribute 'port'". An error string in the output is not silent. Both halves of what I asked about are true — it names the exact regression and says to skip 1.3.4 — so only that one word needs removing.

3. 1.4.1 — "gates every release pipeline" overstates. The page says the unit-test workflow gates "the packaging, vendor-cron and documentation workflows". A documentation workflow is not a release pipeline, and "every" is not claimed. Naming the three is shorter and true.

4. Nothing enforces the new invariants, and this is the item I will not waive. The file's header still claims "there is exactly one copy of each entry and nothing to keep in step by hand" — no longer true of the file it describes. The PR creates 37 hand-maintained duplications of version, release date and summary, and adds zero tests. The concrete failure is already scheduled: when 1.5.0 ships, its page heading gains a date while the index bullet still reads (unreleased), and nothing catches it. The check is ~15 lines in RepositoryStateTests in tests/project/test_changelog_md.py — which already reads the real tree and already has the pruned-docs/ skip guard — asserting the bullets' (version, date) pairs equal each page's heading and that bullet order equals read_toctree()'s.

All five mechanical claims verified, and two more strongly than I framed them. read_toctree() was read before the exit code was trusted: :hidden: is harmless because line 310's if body.startswith(':'): continue discards any option line, exactly as it already did for :maxdepth: — and the 37 toctree lines are byte-identical before and after (md5 c43c19f1…). The sdist claim was checked by running the real setuptools 84.0.0 directive processor over MANIFEST.in rather than reading it: changelog.rst not in sdist, changelog/1.5.0.rst in — because recursive-include docs/source/changelog *.rst needs a path separator and so cannot re-add the pruned index. 47 tests pass under plain unittest. All 37 :doc: links resolve in built HTML with zero literal :doc: left. Warning delta 0, quoted from Sphinx's own summary line — build succeeded, 58 warnings both sides, sorted logs byte-identical.

And it corrected my brief on something that makes the result stronger, not weaker. I said an unresolved :doc: is silent without nitpicky or -W. Wrong — sphinx's std domain registers 'doc': XRefRole(warn_dangling=True), so a dangling :doc: warns regardless. I confirmed warn_dangling=True is present in that file. So delta-0 across 140 added lines of cross-references is real evidence that none of them is broken, which I had discounted.

Items 1-3 are one-line prose edits; item 4 is the coverage rule. Sent to the author.

[JarryShaw]

GOOD TO GO on c7544a23b. All four items fixed, verified by me rather than from the hand-back.

delta since ebf574d17:  docs/source/changelog.rst 20 +-,  tests/project/test_changelog_md.py +30
                        still exactly one commit above main

1. "#326 and #509" / "roughly 140" occurrences ....... 0
2. "silently" occurrences ............................ 0
3. :49 "gates the packaging, vendor-cron" ............ the three workflows the page names
4. test_index_summary_bullets_track_each_pages_own_heading  at :700,
   inside RepositoryStateTests (:674)                 correct class

Ran the new test myself at this head, in a tree I asserted — that was the one item I said I would not waive:

TREE /tmp/v909/pcapkit/__init__.py
test_index_summary_bullets_track_each_pages_own_heading ... Ran 1 test  OK
tests.project.test_changelog_md ........................... Ran 48 tests  OK
util/changelog_md.py --check .............................. in step, exit=0

It went in the right place — RepositoryStateTests already reads the real tree and already carries the pruned-docs/ skip guard, so the check runs where it can see live state rather than a fixture. And the author proved it fails against the pre-PR file by monkey-patching INDEX to the toctree-only version and getting an AssertionError naming all 37 missing bullets. That is the drift I was worried about: when 1.5.0 ships, its page heading gains a date and a stale index bullet would still read (unreleased) — now caught.

The 1.5.0 bullet dropped the count and range entirely, which was the right call over fixing the number in two places. The root defect stays where it belongs, in docs/source/changelog/1.5.0.rst:7-8, and is tracked on #657 — which I have moved to review: needs-changes for it. So this PR no longer carries a false claim, and the remaining copy has an owner.

It also took the 0.15.5 readability nit I flagged as optional — "Fixed data DictDumper cannot encode by adding a fallback encoder" became "Added a fallback encoder so DictDumper no longer raises on data it cannot encode." Worth having, since the index is the more-read surface.

And it used Sphinx's own summary line this round — build succeeded, 42 warnings, identical before and after, sorted lines byte-identical apart from four non-deterministic dependency-check lines. That is the settled method here after three earlier measurements disagreed.

Ready for you to merge. I am not merging.