Skip to content

docs(conventions): write the outstanding rulings onto their pages - #2599

Merged
JarryShaw merged 2 commits into
mainfrom
docs/2557-2563-convention-rulings
Nov 2, 2026
Merged

docs(conventions): write the outstanding rulings onto their pages#2599
JarryShaw merged 2 commits into
mainfrom
docs/2557-2563-convention-rulings

Conversation

@JarryShaw

@JarryShaw JarryShaw commented Nov 1, 2026

Copy link
Copy Markdown
Owner

What is the purpose of your pull request?

  • docs — documentation only

Description of your pull request and other information

This writes the rulings the convention pages had not caught up with onto their pages, each citing where it was settled. Every factual claim was checked against the code.

#2557:

  • utilities-or-corekit.rst records the compat ruling: version gates, not probes.
  • protocol-layer-placement.rst records IP_Pseudo in misc, and no longer reads RFC 1812 §4.1 as a complete list. The OSPF docstring is aligned with it.
  • reassembly-integration.rst says where each of its points was ruled.
  • protocol-family-grouping.rst records that AH and ESP are selected by IPsec/IPv6_Ext only under IPv4.
  • mint-criterion.rst adds CommandType to the flag registries.

#2563: protocol-family-grouping.rst gains "The SSL Family" section and the dispatcher criterion: a registry binds a family's base only where its code cannot tell the members apart.

The nitpicky docs build's warning set is identical to main's, and 'Chained Records' is unchanged.

Closes #2557
Closes #2563

@JarryShaw JarryShaw added docs Pull requests that change documentation only (docs: subject prefix) review: good-to-go Cross-review at the current head says ready; CI state is separate labels Nov 1, 2026
@JarryShaw

JarryShaw commented Nov 1, 2026

Copy link
Copy Markdown
Owner Author

GOOD TO GO at ae40a3eaa, after a Sonnet review and a nit fold that I checked myself. Every ruling #2557 and #2563 list is on its page, and each claim matches the code. The CommandType value-table probe, AH/ESP under IPv6, and the 1709 matcher's actual reach were all checked. The warning sets are identical to main's, and 'Chained Records' is byte-identical.

@JarryShaw

JarryShaw commented Nov 1, 2026

Copy link
Copy Markdown
Owner Author

Two questions for the owner (the PR is complete either way):

  1. Citing a ruling that lives only in a PR thread. documentation.rst says to name the issue, but has no rule for this case. (a) Cite the issue the PR closes, as "ruled in review of X (:issue:N)". Cite the PR with "no issue holds the ruling" only when it closes none. (b) Always cite the PR. Recommend (a), which is what this PR does, plus a line recording it under "Paraphrasing a Ruling".
  2. reassembly-integration.rst, point 4: reassembly never uses an algorithm pcapkit invents. On fix(reassembly): pin DTLS handshake buffers at declared message length #2469 you first said that where no RFC specifies one, the best available algorithm is used, and then "keep RFC driven" settled the DTLS case. Should point 4 also state the first rule? (a) Yes, add it. (b) No, keep only the RFC-driven rule. Recommend (b) unless you meant it generally.

@JarryShaw JarryShaw added the needs: decision Waiting on the maintainer to decide — not blocked by other work label Nov 1, 2026
@JarryShaw JarryShaw moved this to Needs decision in PyPCAPKit Nov 1, 2026
@github-actions

github-actions Bot commented Nov 1, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Coverage: 94.03% (unit tier, Python 3.15, 3ac73ccf7, Unit Tests run success)

Package Statements Missed Branches Partial Cover
pcapkit (top level) 104 4 20 2 95.16%
pcapkit/const 20093 144 2712 125 98.78%
pcapkit/corekit 2605 74 818 37 96.52%
pcapkit/dumpkit 281 3 100 3 98.43%
pcapkit/foundation 3360 27 1186 32 98.70%
pcapkit/interface 138 4 52 3 96.32%
pcapkit/protocols 20363 220 5374 204 98.34%
pcapkit/toolkit 961 28 342 10 96.32%
pcapkit/utilities 506 7 144 5 98.15%
pcapkit/vendor 5009 2222 1148 182 52.31%

Per-file detail: the coverage-html artifact of this run.

@JarryShaw

JarryShaw commented Nov 1, 2026

Copy link
Copy Markdown
Owner Author
  1. (a)
  2. (b)

@JarryShaw

JarryShaw commented Nov 1, 2026

Copy link
Copy Markdown
Owner Author

Owner chose 1 (a) and 2 (b), paraphrased:

  1. Citation scheme: a ruling given on a PR thread is cited by the issue that PR closes, as "ruled in review of X (:issue:N)". When the PR closes no issue, it is cited by :pr: with "no issue holds the ruling". That is the scheme this PR already uses. The rule is being added under documentation.rst's "Paraphrasing a Ruling", folded into the docs(conventions): rulings and facts the convention pages have not caught up with #2557 commit.
  2. Reassembly point 4 keeps only the RFC-driven rule, as written here.

@JarryShaw JarryShaw removed the needs: decision Waiting on the maintainer to decide — not blocked by other work label Nov 1, 2026
@JarryShaw JarryShaw moved this from Needs decision to In review in PyPCAPKit Nov 1, 2026
@JarryShaw
docs(conventions): write the rulings from their threads onto the pages (
1841458 
#2557)

- utilities-or-corekit: compat holds compatibility implementations and
  re-exports only, behind version gates; a platform-independent helper
  such as fromtimestamp gets its own module. States what the #1709
  probe test matches.
- protocol-layer-placement: misc also holds the checksum pseudo-headers,
  with the IP_Pseudo placement ruling; the internet row and the routing
  section read RFC 1812's list as the Internet Layer protocols it names,
  not as everything internet holds. The OSPF class docstring and the
  layer-placement test's docstring say the same.
- reassembly-integration: the intro names where points 1-3 were ruled,
  and that point 4 rests on the DTLS case #2469 settled.
- protocol-family-grouping: AH and ESP are selected by IPsec and IPv6_Ext
  only where IPv4 carries them.
- mint-criterion: CommandType caches in the value table, as Flags does.
- A ruling cited to an issue whose thread does not hold it says so.

Closes #2557
@JarryShaw
docs(conventions): record the SSL family and the dispatcher criterion (…
3ac73cc 
…#2563)

- protocol-family-grouping: a new SSL Family section records the
  grouping ruled on #2441: SSL over SSLv2, TLS and DTLS, one TLS class
  with a dynamic alias, SSLv3 as the thin subclass, and how SSLv2 is
  reached on port 443.
- Dispatching Bases opens with the criterion: a base is bound, and
  dispatches, only where the registry code cannot tell the members apart
  (ruled for IGMP on #2444); IP, IPsec and SSL are never bound (ruled for
  SSL on #2441).
- Member Shapes lists SSLv2, TLS and DTLS; Grouping by Name names SSL.
- The intro leaves each ruling to name its own thread.

Closes #2563
@JarryShaw
JarryShaw force-pushed the docs/2557-2563-convention-rulings branch from ae40a3e to 3ac73cc Compare November 1, 2026 23:52
@JarryShaw

JarryShaw commented Nov 1, 2026

Copy link
Copy Markdown
Owner Author

GOOD TO GO at 3ac73ccf7, after a fold I checked myself. The owner's citation rule is now under "Paraphrasing a Ruling" in documentation.rst, inside the #2557 commit, and it cites itself in its own form. The delta is 4 lines in that file only. Both commits stay on f4aa57742, and the conventions-claims, roles and comment-ref tests pass.

@github-actions github-actions Bot added this to the PyPCAPKit v1.6 milestone Nov 2, 2026
@JarryShaw
JarryShaw merged commit 6e9203e into main Nov 2, 2026
61 checks passed
@JarryShaw
JarryShaw deleted the docs/2557-2563-convention-rulings branch November 2, 2026 02:21
@github-project-automation github-project-automation Bot moved this from In review to Done in PyPCAPKit Nov 2, 2026
@JarryShaw JarryShaw removed the review: good-to-go Cross-review at the current head says ready; CI state is separate label Nov 2, 2026
@JarryShaw JarryShaw mentioned this pull request Nov 2, 2026
Open
JarryShaw added a commit that referenced this pull request Nov 2, 2026
@JarryShaw
docs(changelog): fold DCCP, InARP's move and main's latest wave into …
42280b4 
…1.6.0 (#2449)

- Added: DCCP, its checksum over the IP pseudo-header, register_dccp and
  register_dccp_option, and the pcapkit.const.dccp registries (#2593).
- Folded into unreleased entries: LinuxSLL's stop on its ARPHRD path
  (#2587) and ARPHRD's __proto_dest__ (#2598), SSLv2 records chained in a
  segment (#2585), the checksum's move to pcapkit.corekit.checksum.internet
  (#2586), and IGMPv2's and IGMPv3's versioned name (#2590).
- Breaking: InARP moves to pcapkit.protocols.link.inarp with no re-export,
  joining the DRARP entry (#2596).
- Changed: the conventions' new rulings (#2599), the milestone workflow's
  next-open-milestone lookup (#2591), the PyPy protocols shards (#2604).
  Fixed: a handled next-layer refusal is quiet under beholder (#2597); the
  IPX crawlers restore sys.path (#2601).
- CHANGELOG.md regenerated; util/changelog_md.py --check passes.
This was referenced Nov 2, 2026
Open
Merged
Merged
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

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

Projects

PyPCAPKit
Status: Done

Milestone

PyPCAPKit v1.6

1 participant

@JarryShaw