docs(contributing): paraphrase the quoted rulings on the conventions pages, and stop asserting them as literal strings

Describe the bug

The convention pages record the maintainer's design rulings by block-quoting him verbatim, and several tests assert those quoted sentences as literal strings. He has asked to be paraphrased instead (#918). Two problems, one stylistic and one functional:

The pages read like a transcript rather than a set of conventions.
His casual phrasing is a build dependency. tests/project/test_conventions_doc_claims.py asserts the literal 'I prefer (2) directly.' and 'I lean on 1.' appear on a page, so a one-line reply in a thread is load-bearing in CI.

Reproduction

$ grep -rc verbatim docs/source/contributing/conventions/*.rst
extension-header-subclassing.rst:2
mint-criterion.rst:3
registry-protocol.rst:7
sentinel-convention.rst:5

$ grep -n "assertIn('I prefer\|assertIn('I lean\|not to be loud" tests/project/test_conventions_doc_claims.py
854:        self.assertIn('they should follow house convention and not to be loud', flat,
891:        self.assertIn('I prefer (2) directly.', flat,
893:        self.assertIn('I lean on 1.', flat,

Expected behavior

Paraphrase the substance, keep the attribution by issue number, and pin the claim rather than the wording:

Prose: "the owner ruled on fix(protocols): widen the two kept get overrides in mh.py to accept default #940 that a redundant override is deleted rather than widened", not a block quote.
Tests: assert the page's own claim and the tree fact behind it. Never assert a sentence he wrote.

Scope

The four (soon five) pages under docs/source/contributing/conventions/.
Every assertIn in tests/project/ that pins a quoted sentence.
Out of scope: the quotes docs(contributing): record the get-override rulings on the conventions page (#918) #948 itself introduces — that PR is paraphrasing its own four as part of its current revision. And historical issue/PR comments, which stay as written; rewriting weeks of threads is noise and the originals are his words in their own context.

Notes

Sequenced behind docs(contributing): record the get-override rulings on the conventions page (#918) #948 and docs: harvest every settled design ruling into the convention docs, and split them per category #918 Part 1, both of which are actively editing these files; doing this first would conflict on every page.
The registry-protocol.rst count of 7 includes one legitimate use of the word (forwards ``default`` verbatim at :307), so the real quote count there is 6.

System information

pcapkit commit 210bdb419, Python 3.14.7, CPython, Linux.

docs(contributing): record the get-override rulings on the convention…

Blocked, with a checkable condition rather than a remembered one. This issue rewrites prose in the same files two open pull requests are editing, so doing it now would conflict on every page.

$ gh pr list -R JarryShaw/PyPCAPKit --state open --json number,files \
    -q '.[]|"#\(.number) \(.files|map(.path)|map(select(test("conventions|test_conventions")))|join(" "))"'

docs: retarget every dead :rfc:959 sub-section anchor (#944) #946 — tests/project/test_rfc_anchor_fragments.py and four roles in docs/source/contributing/conventions/registry-protocol.rst.
docs(contributing): record the get-override rulings on the conventions page (#918) #948 — registry-protocol.rst, the new process.rst, index.rst and tests/project/test_conventions_doc_claims.py, which is where the quoted-string assertions this issue removes actually live.

Unblocks when both are merged; nothing else gates it. The scope is unchanged from the body — the pages plus the assertIn calls that pin a sentence, with #948's own four quotes already paraphrased there rather than here.

One addition to scope found since filing: pyproject.toml:115 and :224 also quote the maintainer verbatim in comments. Same treatment — paraphrase, keep the issue number.

One more item for this issue's scope, found by #948's round-11 review and deliberately not fixed there.

tests/project/test_conventions_doc_claims.py indexes vars(Method)['get'], vars(Command)['get'] and vars(OptionType)['get'] directly. If any of those three ever folds its own get into the inherited base — exactly what #940 did to the mh/ngap helpers — the test raises a bare KeyError: 'get' instead of a diagnostic AssertionError.

It fails loudly either way, so no regression passes silently; this is diagnostics quality rather than correctness, which is why #948 was not held for it. The sibling at :920 already does it right, using assertNotIn('get', vars(klass)) — membership, not indexing.

Also worth folding in while these files are open: the new assertNotIn guarding the dependabot attribution pins one exact phrasing, so a differently-worded re-attribution of github_actions would slip past it. An inherent limit of substring pinning that this suite documents elsewhere, but worth a second look when the paraphrase pass rewrites that section anyway.

Scope now: the pre-existing verbatim quotes across the convention pages, the pyproject.toml:115/:224 comments that quote the maintainer, these two test-robustness items, and — from #948's round 8 — the Audit, per Class population figures (127 EnumRegistry subclasses, 117 int-valued, 151 total, the R1_Counter collision), which need the runtime enumeration walk extended to pin.

Still blocked: #948 is review: good-to-go and awaiting the maintainer's merge; this issue rewrites the same files.

docs(contributing): paraphrase the quoted rulings, and pin claims not…

Merge pull request #951 from JarryShaw/docs/949-paraphrase-quoted-rul…

docs(contributing): refer to the owner by role, not by gendered pronoun

docs(sphinx): add opt-in issue, pr and discussion roles, and convert …

Navigation Menu

Repository navigation

docs(contributing): paraphrase the quoted rulings on the conventions pages, and stop asserting them as literal strings #949

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

docs(contributing): paraphrase the quoted rulings on the conventions pages, and stop asserting them as literal strings #949

Description

Activity

JarryShaw commented on Sep 30, 2026

JarryShaw commented on Sep 30, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions