Skip to content

docs: #1103 round 10 -- close the whole-repo prose sweep - #2432

Merged
JarryShaw merged 1 commit into
mainfrom
docs/1103-round10-whole-repo-prose
Oct 29, 2026
Merged

JarryShaw merged 1 commit into
mainfrom
docs/1103-round10-whole-repo-prose

Conversation

@JarryShaw

Copy link
Copy Markdown
Owner

Please follow the guide below

  • 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 under docs/source/changelog/ and regenerated CHANGELOG.md, if the change is user-visible -- N/A, no user-visible behavior change (see below)

What is the purpose of your pull request?

  • docs — documentation only

Description of your pull request and other information

Round 10 of the #1103 whole-repo prose sweep -- the closing-condition test (per the #719 precedent): the issue only closes once a full pass finds nothing new, not a delta. Unlike round 9 (a scoped mop-up), this round fanned out across the entire repo again from scratch.

A full re-grep found exactly 3 items, all outside the carve-outs round 9 already settled:

  • pcapkit/protocols/protocol.py + pcapkit/foundation/registry/protocols.py: RegistryError said "protocol must be a Protocol subclass" while the adjacent issubclass(protocol, ProtocolBase) check and the Raises: docstring both say ProtocolBase -- fixed the message text to match, with the three test assertions that locked the old string.
  • tests/foundation/reassembly/test_deferred_pickle_2423_unit.py: a docstring said "this pull request's earlier commit", stale now that fix(reassembly): make Deferred picklable under protocol 0 and 1 #2424 landed as one squashed commit on main -- reworded to cite the issue instead of the PR's own history.
  • tests/protocols/transport/test_tcp_mptcp_option_attr_2293_unit.py: a cross-reference cited the nonexistent module pcapkit.corekit.fields.enums.EnumField; the real path is pcapkit.corekit.fields.numbers.EnumField.

No executable logic changed: an AST structural diff (ignoring string constants) against origin/main is identical for every touched file. The RegistryError fix only changes the text of a raised message, not what triggers it or any control flow -- flagging this transparently since it's a string literal in code rather than a pure comment/docstring, even though it's prose-only in effect.

Two relayed findings were checked directly and rejected because they didn't survive inspection against current main: a transport.py:188-189 claim and a registry/protocols.py:370 claim both already read correctly on this base (both were generated against a pre-round-9 tree). Re-swept pcapkit/vendor/ process() methods for siblings of the #2429/#2430 bug shape -- none found. docs/source/ and the rest of tests/ came back clean.

Verification: the 4 directly affected test files pass (45 passed, 219 subtests), the existing tests/project/test_docs_issue_pr_roles_1103_unit.py guard passes (9 passed), the full tests/project/ suite passes (2107 passed, 80 skipped, 10279 subtests, 0 failures), and a docs build on the pinned toolchain (docs/requirements.txt) against both this branch and origin/main produces the identical single pre-existing warning (TransType ambiguous cross-reference) -- zero new warnings.

One open question flagged for a maintainer decision rather than resolved unasked: CONTRIBUTING.md's commit-type list (and the PR template above) doesn't include build, but two merged commits (#2061, #2062) used build: as their subject prefix. Could be intentional (those commits folding under ci's "workflows or build tooling" description was the intent, and the two commits are themselves the drift) or could mean build should be added as a recognized type. Not fixed in this PR since it's a project-convention call, not stale prose.

Closes #1103.

Round 10, the closing-condition test: a full re-grep across the entire repo
found exactly 3 items, all outside the carve-outs round 9 already settled.

* pcapkit/protocols/protocol.py + foundation/registry/protocols.py:
  RegistryError said "protocol must be a Protocol subclass" while the
  adjacent issubclass() check and the Raises: docstring both say
  ProtocolBase -- fixed the message text to match, with the three test
  assertions that locked the old string.
* tests/foundation/reassembly/test_deferred_pickle_2423_unit.py: a docstring
  said "this pull request's earlier commit", stale now that #2424 landed as
  one squashed commit on main -- reworded to cite the issue instead of the
  PR's own history.
* tests/protocols/transport/test_tcp_mptcp_option_attr_2293_unit.py: a
  cross-reference cited the nonexistent module
  pcapkit.corekit.fields.enums.EnumField; the real path is
  pcapkit.corekit.fields.numbers.EnumField.

No executable logic changed: an AST structural diff (ignoring string
constants) against origin/main is identical for every touched file, and the
RegistryError fix only changes the text of a raised message, not what
triggers it.

Re-verified and rejected two relayed findings that didn't survive a direct
check: a transport.py:188-189 and a registry/protocols.py:370 cross-reference
claim both already read correctly on this base. Re-swept vendor/process()
for siblings of #2429/#2430 -- none found. docs/source and the rest of
tests/ came back clean.

Build: tests/protocols/test_register_class_guard_unit.py,
tests/foundation/registry/test_protocols.py,
tests/foundation/reassembly/test_deferred_pickle_2423_unit.py,
tests/protocols/transport/test_tcp_mptcp_option_attr_2293_unit.py and
tests/project/test_docs_issue_pr_roles_1103_unit.py pass.

Closes #1103.
@JarryShaw JarryShaw moved this to In review in PyPCAPKit Oct 29, 2026
@github-actions github-actions Bot added this to the PyPCAPKit v1.5 milestone Oct 29, 2026
@JarryShaw JarryShaw added docs Pull requests that change documentation only (docs: subject prefix) review: running A cross-review is in flight against the current head - no verdict yet labels Oct 29, 2026
@JarryShaw
JarryShaw merged commit c2f1089 into main Oct 29, 2026
63 checks passed
@JarryShaw
JarryShaw deleted the docs/1103-round10-whole-repo-prose branch October 29, 2026 18:28
@github-project-automation github-project-automation Bot moved this from In review to Done in PyPCAPKit Oct 29, 2026
@JarryShaw JarryShaw removed the review: running A cross-review is in flight against the current head - no verdict yet label Oct 29, 2026
@JarryShaw

Copy link
Copy Markdown
Owner Author

Review: NEEDS CHANGES at 1878e452a (Sonnet). This PR is already merged (owner's call, before review landed) — posting the verdict for the record regardless, per standing practice. Three findings, one serious:

  1. Item 1 reverses a ratified owner ruling and should not have been made. The RegistryError message naming Protocol instead of ProtocolBase is deliberate design, not stale prose — fix(foundation): registrar error messages and type hints name the public class, not the Base the guard checks #1016 ruled the message's reader is a third party who should be told Protocol (ProtocolBase is internal-only per its own docstring), the owner approved, docs(protocols): register's Raises name Protocol in some layers, ProtocolBase in others #2316 re-confirmed "not in scope," and docs: prefer Protocol over ProtocolBase in cross-references, per the owner's #1103 ruling #2420 caught a prior pass that flipped it "by mistake." This PR undoes that ruling without citing either issue, and edits test_register_class_guard_unit.py's locked assertions to match — the guard that exists specifically to catch this. Reviewer independently confirmed the behavior and the history. This needs reverting.
  2. test_deferred_pickle_2423_unit.py:248 cites :issue:2424, but #2424 is the merged PR, not the issue — should be `:issue:`2423 (matching line 189 in the same file) or :pr:2424``.
  3. The PR title says Closes #1103, but round 10 found real items (not "clean, nothing new" as the plan called for) — should have been Refs #1103, matching prior rounds' convention.

Everything else verified independently and holds: scope is exactly 6 files/+9/-9, no logic changes, items 2 (minus the citation) and 3 of the original findings are correct, full tests/project/ and docs-build claims reproduce.

Opening a follow-up PR to revert item 1 and fix item 2's citation, and reopening #1103 since this round found real, unresolved items.

JarryShaw added a commit that referenced this pull request Oct 29, 2026
…#2434)

#2432 (round 10 of #1103) changed register's RegistryError message from
"...must be a Protocol subclass" to "...must be a ProtocolBase subclass"
in pcapkit/protocols/protocol.py and foundation/registry/protocols.py, and
updated the locked assertions in tests/protocols/test_register_class_guard_unit.py
and tests/foundation/registry/test_protocols.py to match. This was a mistake.

* The wording naming Protocol (not ProtocolBase) is a deliberate, ratified
  decision: #1016 ruled the message's reader is third-party code, who should
  be told to subclass Protocol -- ProtocolBase's own docstring says it is
  "for internal use only". The owner approved that reasoning, #2316
  re-confirmed it as out of scope to change, and #2420's commit explicitly
  records "the error message names Protocol" as the kept half of the split
  between the Raises: clause (ProtocolBase) and the raised message
  (Protocol). #2420 also notes it already caught and corrected one prior
  accidental flip of this exact wording.
* Reverted both raise sites and the four locked test assertions back to
  "Protocol subclass".
* Also fixed a citation left by #2432: tests/foundation/reassembly/
  test_deferred_pickle_2423_unit.py cited :issue:`2424` (the merged PR, not
  an issue) where it meant the underlying fix, tracked as #2423 -- matches
  the file's existing :issue:`2423` citation style and the changelog's own
  "(:issue:`2423`, :issue:`2425`, :pr:`2424`)" citation.

#2432's other two fixes (a stale docstring, a cross-reference to a moved
EnumField) are correct and untouched.

Refs #1016, #2316, #2420
Refs #1103

Build: tests/protocols/test_register_class_guard_unit.py,
tests/foundation/registry/test_protocols.py,
tests/foundation/reassembly/test_deferred_pickle_2423_unit.py pass; full
tests/project/ run shows no new failures (13 pre-existing failures, all in
unrelated subprocess/network-dependent tests, none touching these files).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Pull requests that change documentation only (docs: subject prefix)

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

docs: #719-style prose sweep after the #1090–#1102 defect wave

1 participant