docs(contributing): heading casing per the #719 ruling

[JarryShaw]

• Searched for similar pull requests
• Followed the coding style (make pylint, make mypy, make isort)
• make test passes, and a test case covers the change
• Added a changelog entry — N/A — 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

First slice of the heading ruling on #719, covering docs/source/contributing/.

62 headings in scope: 24 already correct, 16 re-cased, 22 rewritten. The
rewrites are the substance — the ruling is not a casing rule. A heading like
What a Failed Lookup Raises was already Title Case and still broke it, being a
clause rather than a title; it is now Failed-Lookup Exceptions. The full
old → new list is in a comment below, since it is the reviewable part and does
not belong in the body.

The dividing line used: a finite verb makes it a sentence and earns a rewrite; a
gerund or infinitive phrase is a noun phrase and only needs casing, so
Running the tests → Running the Tests rather than being reworded.

Headings are link targets, so five implicit `Text`_ references were
repointed in releasing.rst and workflows.rst, and one stale docstring quote
corrected in tests/corekit/test_sentinel_exports_unit.py:420. Every underline
re-measured against its new text: 62 checked, zero shorter than their heading.

No test assertion changed — test_conventions_doc_claims.py slices on .. _label:
anchors and list-table markers, never heading text. Six coupled modules green.

[JarryShaw]

The 22 rewrites, old → new — the reviewable part, kept out of the body.

releasing.rst

• :107 Each job past version_check reads its own evidence, not a shared proxy → Per-Job Evidence, Not a Shared Proxy
• :153 Reading your own evidence is not enough by itself, though → The Skip-Cascade Guard
• :189 The pipeline, and why one approval is enough → One Approval, Whole Release

conventions/registry-protocol.rst

• :3 Where the registry protocol lives → The Registry Protocol
• :30 The Two Tiers, and What Lives on Each → The Two-Tier Hierarchy
• :112 What a Failed Lookup Raises → Failed-Lookup Exceptions
• :175 What a get Override May and May Not Do → get Override Obligations
• :293 Case Sensitivity Is RFC-Directed → RFC-Directed Case Sensitivity

conventions/process.rst

• :3 How the repository itself is run → Running the Repository
• :15 What the all extra carries → The all Extra
• :66 What a changelog entry is → Changelog Entry Granularity
• :130 How the issue and pull request labels work → Issue and Pull Request Labels
• :248 What breaking marks → The breaking Label

conventions/extension-header-subclassing.rst

• :3 Which bases an IPv6 extension header names → Extension-Header Base Classes
• :44 The code cannot be used as evidence → The Shared-Registry Trap
• :71 The operative test is what the RFCs say → The IPv4-Payload Test
• :112 The declaration is what carries the classification → Explicit Base Declarations
• :131 The base is named IPv6_Ext, and nothing else → Naming the Base IPv6_Ext
• :148 ESP is an extension header, and still cannot short-circuit → ESP's Two Facts

conventions/mint-criterion.rst

• :3 When an unrecognised value may mint a member → Minting an Unrecognised Value
• :96 Why the company names are suffixed → Suffixed Company Names

conventions/sentinel-convention.rst

• :109 What to implement, and what not to → Per-Sentinel Dunder Methods

Two kept deliberately as-is rather than reworded: `Why a Class and Not ``object()```
reads as an accepted FAQ-style title, and the 16 gerund-headed phrases are noun
phrases, not sentences.

[JarryShaw]

NEEDS CHANGES at c7f3fd66a — opus cross-review, round 1. Three real defects,
all fixed at 2dc35a5cd. One of them was my error, not the author's.

I claimed exactly one stale cross-reference survived the rename. There were
five. All confirmed by reading the lines:

pcapkit/corekit/sentinels.py:11,:463              "Naming a sentinel" section
tests/corekit/test_sentinel_exports_unit.py:186,:190   same
tests/project/test_conventions_doc_claims.py:819  *Where the registry protocol lives*

sentinels.py:11 is a shipped module docstring that renders into the published
API docs, so a reader following it would Ctrl-F a string no longer on the page.
Fixed all five; the last also had a paraphrase of the old get heading, retitled
to *The Registry Protocol*.

My sweep was scoped to a hand-picked list of 8 strings; my second sweep also
undercounted, because extracting old headings from the diff misses any whose
underline is not adjacent in the hunk. A whitespace-flattened sweep over all 38
strings and every tracked file is the method that works.

A prose break the rename caused, registry-protocol.rst:115: "Two rules govern
it" lost its antecedent when the singular What a Failed Lookup Raises became
plural Failed-Lookup Exceptions. Now reads "govern which exception a failed lookup
raises".

Two headings misdescribed their sections, both renamed:

• One Approval, Whole Release → The Release Pipeline. The section opens
  immediately with a mermaid flowchart; the approval prose starts 34 lines later. The
  graph is the page's most navigable artefact and was unfindable from the TOC.
• Naming the Base ``IPv6_Ext``` → **The Retired IPv6_GenericExt Name``**. The
  section gives no naming guidance — it is rename history plus a prohibition.

62 underlines re-checked, zero short. 57 tests OK. Note the PR now touches
pcapkit/corekit/sentinels.py — a docstring only, but it is no longer docs-only.

[JarryShaw]

NEEDS CHANGES at 2dc35a5cd — opus cross-review, round 2. One finding, and it
was my regression from round 1, now fixed at 4308d62a1.

Rewrapping that paragraph with sed left a 126-character line at
registry-protocol.rst:116. Measured: the file's 90th-percentile line length is
84, and the only other lines over 95 are two table borders (:37, :41), a
table cell (:39) and a mermaid node label (:151) — all unwrappable. So mine was
the sole wrappable prose line over 95, in a PR whose subject is prose hygiene.
Nothing enforces a width here and Sphinx reflows anyway, so it was cosmetic — but
self-inflicted this round, not pre-existing: on main the same two lines were 85
and 87.

Now 82 / 41 / 84 / 84. Swept every added .rst line across all 12 files:
zero over 95.

Round 2 independently confirmed the substance, having re-derived rather than
trusted my list — it rebuilt the sweep over 40 strings (all 38 pre-PR headings
plus both round-1 interim titles) across 1,029 files, and found zero hits on
either interim title, so the two renames introduced no new dangling references. All
five stale references confirmed gone. Implicit `Text`_ references: 0
unresolved across docs/source. Both new headings exact on underline (20 and 36),
underline characters unchanged, hierarchy intact. sentinels.py confirmed
docstring-only — two single-line hunks, module imports clean, __all__ unchanged.

It flagged the test run as UNVERIFIED on its side, having timed out. I have run
it at this content: Ran 57 tests ... OK (skipped=1).

ESP's Two Facts, The Shared-Registry Trap and Two Ways to Start a Release
remain unchanged and forwarded as wording preferences — re-confirmed accurate as
written, so none is a defect.

[JarryShaw]

GOOD TO GO at 4308d62a1 — opus cross-review, round 3 clean.

Verified on my side rather than relayed: git diff 2dc35a5cd 4308d62a1 is one
file, one hunk, +2/−1 — exactly the line break, nothing else moved in the amend.
The rewrap puts the whole #923 link on one line, so the break falls before it
rather than inside it, and a docutils parse of the paragraph returns 1 paragraph
node and 1 reference node with the correct refuri.

Two methodological notes from the review worth keeping, both of which would have
misled a less careful check:

• 4308d62a1 is a force-push, not a child of 2dc35a5cd (confirmed:
  git merge-base --is-ancestor is false). So gh api compare/A...B returns the
  three-dot diff against the merge base and renders the whole 12-file branch diff —
  it cannot answer "did anything else move". Pairwise file comparison can.
• A naive docutils <paragraph> count reported 7, because bare docutils does
  not know :exc:/:class:/:mod: and emits a system_message containing its own
  paragraph per unknown role. Stripping those first gives the real answer, 1. The
  naive count would have read as an accidental paragraph split.

It also found a pre-existing 99-character prose line at pep.rst:536, which I
confirmed is byte-identical on main and untouched by this PR — so it belongs to
whatever slice picks up pep.rst next, not here.

Honest about its own gap, which I'd rather have than a false corroboration: its
background test run produced 0 bytes and was reaped, so it can neither
corroborate nor dispute my Ran 57 tests ... OK (skipped=1). One measurement, not
two. What bounds the risk is that both test-module changes are docstrings and
test_conventions_doc_claims's assertions key on :role:target`` needles, never
heading text.

ESP's Two Facts, The Shared-Registry Trap and Two Ways to Start a Release
remain forwarded as wording preferences — accurate as written, none a defect.

[JarryShaw]

The red mark here is an infrastructure stall, not this diff. Root-caused rather
than reported.

Required checks passed failed because engine-tests reported cancelled, and that
because Engines Python 3.13 (PCAP_CT) was killed at the timeout-minutes: 30 on
unit-tests.yml:327 while still inside apt-get update:

15:58:06-ish  Get:… archive.ubuntu.com … InRelease
+29m52s       ##[error]The operation was canceled.

On the same run (36887906077) the other five PCAP_CT legs finished in 39–81
seconds. A docs change cannot affect an engine's system-package install.

Filed as #974 with the fix — apt retries and timeouts, plus a step-level cap. I am not
re-running the workflow; that is yours. The verdict on this PR stands on its content.