docs(contributing): cut the contributing pages and repair drifted line references

[JarryShaw]

• 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 — I ran tests/project only (268 passed, 1 skipped, 864 subtests), not the full suite
• Added a changelog entry under docs/source/changelog/ and regenerated CHANGELOG.md, if the change is user-visible — N/A, prose only, no user-visible behaviour

What is the purpose of your pull request?

• fix — corrects a defect
• feat — adds a feature
• perf — changes performance, not behaviour
• refactor — changes neither behaviour nor performance
• test — tests only
• docs — documentation only
• ci — workflows or build tooling
• chore — anything else

---

Description of your pull request and other information

The docs/source/contributing/ slice of #719. −27 lines net across seven of the eleven pages; conventions/index.rst, extension-header-subclassing.rst, sentinel-convention.rst and testing.rst are untouched.

The accuracy half is the larger part of this. The file:line references into .github/workflows/ had drifted badly — create-release.yml by 50 to 200 lines. I verified the rewritten ones rather than taking them on trust: 17 specific citations were read back against the real files and every one lands on the right construct (required-checks: at unit-tests.yml:1141, its if: at :1144, changelog: at :904, gate: at :931, the four environment:/needs: pairs in create-release.yml at 345/348, 447/449, 522/527 and 623/626, tag_name at 425, 603 and 843, the unreleased-changelog guard at 402). All 31 references in the subtree are in range for their target file.

Also fixed: a Compat Python ${{ matrix.python-version }} literal split across a source line break, which reST will not render as a literal. And releasing.rst carried a pointer saying the tag-push bypass is explained "in the next section" — that section is about skip cascades and never explained it, so the dangling promise is gone rather than left pointing nowhere.

Citations are frozen, per the ruling on #719 that they are design rationale rather than timed context. Every :issue:/:pr:/:discussion: role, bare #nnn and issue URL is byte-identical per file. Two rulings recorded in this subtree were specifically protected and survive: that the changelog and tests/ are exempt from the cite-the-issue rule, with the reasoning that under tests/ the pull request is often the only durable pointer; and that a ruling is written in one's own words rather than quoted.

Timed context is cut — "today", "currently", "to date", "commented out since 2023", a two-pass sweep narrative — while version-bounded breaking-change notes stay, including the two phrased as "used to".

Claims re-derived and found already correct, so left alone: 121 of the 127 registries define _missing_; find_packages returns 73; the label count is 29; 12 mermaid directives on 11 pages; ruleset 23497679's required contexts and strict: true; the ESP, MH and SCTP member and handler counts; and the registered-but-not-dissected sizes in pep.rst.

Not done: no Sphinx build was run for this slice, so there is no build evidence beyond tests/project. The concision pass is also deliberately partial — pep.rst (1119 lines) and much of registry-protocol.rst got only targeted cuts and could still be tightened.

[JarryShaw]

NEEDS CHANGES at c291e5525, fixed at 827b86658 — opus cross-review, a different model from the sonnet that drafted the slice. It read all 64 line-number references in the subtree, not just the ones I named, and found 62 correct and 2 wrong. Both are fixed.

• workflows.rst:217 cited unit-tests.yml:892-900. The rationale it quotes ends at 898; 899 is a bare # and 900 opens an unrelated paragraph that the range truncated mid-sentence. The uniform +197 shift this PR applied maps main's 695-701 to 892-898, so the 900 was drift I introduced while fixing the others. Now 892-898.
• releasing.rst:46 cited test_bump_version.py:494-513. The test spans 494-514 — line 514 is the closing paren of the assertEqual. Now 494-514.

A breaking-change note had been cut, which #719 exempts. process.rst lost "it is what the ruling changed: four of them used to be in all" — the only sentence telling a reader that pip install pypcapkit[all] stopped installing DPKT, Scapy, PyShark and PyPCAPFile. The sibling bullet had also been flattened from "were already excluded … which the ruling leaves untouched" to "are also excluded", losing the what-changed / what-predated-it distinction that justifies two separate bullets. Both restored. The deletion had also left two lines at 121 and 141 columns against the file's 93 maximum; rewrapped.

A claim of mine is withdrawn. I said a Compat Python ${{ matrix.python-version }} literal was split across a source line break and so would not render. That is wrong: reST inline markup legally spans a line break, and docutils 0.22.4 renders main's exact form as a literal. I had tested the wrong construct — an indented continuation, which makes a definition list and genuinely does break, unlike the unindented paragraph continuation main actually uses. The rewrite fixed nothing and dropped the one verbatim string a reader would grep the workflow for, so main's wording is restored and the claim is gone from the message and description.

The review also independently re-derived 121 of 127 registries defining _missing_, confirming the figure #1011 depends on, and verified the citation freeze by occurrence count across all 11 pages.

Separately filed rather than loaded onto this PR: 20 pre-existing nested-inline-markup defects across these pages, all present on main.

[JarryShaw]

Correcting a number in my comment above: I said 20 pre-existing nested-inline-markup defects across these pages. I measured it myself and get 12 — 8 with a literal or role inside **bold**, 4 inside *italic* — across 6 of the 11 pages, not 7: pep.rst 4, releasing.rst 4, and one each in documentation.rst, process.rst, testing.rst and workflows.rst. All 12 are present on main in identical form, so none is a regression here.

I did not reproduce 20 with a detector that flattens wrapped spans and looks for `` literals and roles inside bold and italic. Rather than file an issue on a count I can't derive, I'm leaving these to the docs/source/** concision work under #719, which is already touching these pages — they render the backticks visibly and Sphinx emits no warning, so they are cosmetic rather than load-bearing.

What did warrant its own issue is #1013: docs/source/pcapkit/const/index.rst describes _missing_ as universally minting via aenum.extend_enum, which is the same error this PR's sibling removed from CONTRIBUTING.md, in the page that document points the reader at.

[JarryShaw]

GOOD TO GO at 827b86658 — opus delta re-review, a different model from the sonnet that drafted the slice. All five fixes confirmed: the 892-898 range covers exactly the rationale and stops at its last line; 494-514 is the whole test method and nothing else; both process.rst bullets are byte-identical to main including its wrap, with the :issue:918`` citation intact through the rewrap; process.rst's max width is back to 93 and now at or under `main` on every line; and the restored literal sits whole on one 78-character line.

It also closed the test-count discrepancy from round 1: its 264/5 was its own harness, not the tree — it had measured from an unpacked archive with no .git, so tests/_tiers.py could not run and 4 tier tests skipped. From a real checkout at this head it gets 268 passed, 1 skipped, 864 subtests, matching mine, with no TierGuardWarning.

Third and final correction to the nested-markup count, and the method is the point. I reported 20, then 12. Both were regex artefacts: the first cross-paired the closing ** of one bold span with the opening ** of the next; mine counted * characters inside literals as emphasis. Two independent docutils doctree walks — looking at actual strong/emphasis nodes rather than at text — now give 7 and 8, across the same three files: pep.rst 3, releasing.rst 3 or 4, process.rst 1. I ran mine with every Sphinx role stubbed so a bold span nesting only a role would still be visible, which was the one gap plain docutils leaves.

So the figure is 7-8, not 20 and not 12, all present on main, none a regression here. They render the backticks visibly with no Sphinx warning. I am leaving them to the docs/source/** work under #719 rather than filing an issue on a count two methods still disagree about by one.