From e45d31260a41d26a92c4d302d451a68bbe5bc3d9 Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Wed, 30 Sep 2026 21:40:56 -0400 Subject: [PATCH] docs: cut timed context from the Sphinx prose and root docs (#719) First slice of #719, scoped to ``docs/source/**/*.rst`` and the root documents. The sweep's one objectively testable half: prose saying *when* something changed, or *which* issue changed it, rather than what the code does now. * Remove ~20 timed-context statements across 15 files -- "until GitHub issue #911 moved all four definitions here", "they used to read .../-02.html, which is dead: measured 2026-09-19", "was deleted from the Wikipedia article on 2026-08-25", "Since #617, building a protocol", "one doc-only commit since 1.3.0 ... open and uncommented since May 2024". * Keep version-bounded contract, which is not history: ``.. deprecated::`` directives, the Python-version tables, "requires Python 3.11 or older until 0.12.1 is published", and "upstream is unmaintained, the cap is not expected to lift". * Keep every design decision, reframed from past tense to present where the tense was the only thing dating it -- why ``gap`` is not derived from ``hdl``, the RFC 791 versus TCP conflict-resolution rule, why PCAP-NG revision -03, why no IPX ``LINK``, and both construction-keyword rationales in ``ext.rst``. * Reframe the ``v*``-tag warning in ``releasing.rst`` from a narrative about #888 into the hazard it exists to prevent, keeping the cross-reference to the section that prevents it, so the guard cannot be simplified away again. Out of scope and untouched: ``CHANGELOG.md`` (generated), ``docs/source/changelog/``, and the five ``contributing/conventions/`` pages. ``pytest tests/project tests/corekit/test_sentinel_exports_unit.py``: 246 passed, 1 skipped, 697 subtests, 0 failed. --- docs/source/contributing/releasing.rst | 26 ++++++++----------- docs/source/contributing/workflows.rst | 8 +++--- docs/source/ext.rst | 12 ++++----- docs/source/pcapkit/const/ngap.rst | 3 +-- docs/source/pcapkit/corekit/sentinels.rst | 26 +++++++------------ .../pcapkit/foundation/engines/3rdparty.rst | 7 +++-- .../pcapkit/foundation/reassembly/ip/ipv4.rst | 4 +-- .../pcapkit/foundation/reassembly/ip/ipv6.rst | 7 +++-- .../pcapkit/foundation/reassembly/tcp.rst | 7 +++-- docs/source/pcapkit/index.rst | 4 +-- .../pcapkit/protocols/internet/ipv6_ext.rst | 2 +- docs/source/pcapkit/protocols/misc/pcapng.rst | 10 +++---- docs/source/pcapkit/vendor/ipx.rst | 8 +++--- docs/source/pcapkit/vendor/ngap.rst | 2 +- docs/source/pcapkit/vendor/pcapng.rst | 13 ++++------ 15 files changed, 59 insertions(+), 80 deletions(-) diff --git a/docs/source/contributing/releasing.rst b/docs/source/contributing/releasing.rst index 1b2db072e6..8712e1b7ac 100644 --- a/docs/source/contributing/releasing.rst +++ b/docs/source/contributing/releasing.rst @@ -6,9 +6,7 @@ Release Process This page records the **operational contract** for cutting a release -- what a maintainer is expected to touch by hand, what the workflow is expected to do unattended, and the precautions that follow from the two - being different. Settled on - `#887 `__, which also - collapsed what used to be four separate approvals into one. + being different. The short version: **the only manual edit is bumping** ``pcapkit.__version__``. Everything else -- the ``v*`` tag, the GitHub @@ -228,18 +226,16 @@ Precautions .. warning:: - **A half-finished release used to leave a ``v*`` tag that made every retry - skip silently.** ``github`` creates the tag; if ``pypi`` or ``conda`` then - failed (or was rejected), the tag existed with the upload incomplete, and - the next ``workflow_run``-triggered attempt read ``PCAPKIT_TAG_EXISTS=true`` - with ``ref_name=main`` and skipped every job on that one shared check -- - the run finished green, because skipped is not failed, and nothing in the - UI said a release did not happen. This was - `#888 `__. - - Fixed by `Each job past version_check reads its own evidence, not a shared - proxy`_ above: ``tag``, ``pypi`` and ``conda`` now check whether *their own* - artefact is missing, not whether the ``v*`` tag exists, so an incomplete + **Do not gate a release job on whether the ``v*`` tag exists.** ``github`` + creates the tag before ``pypi`` and ``conda`` upload, so a tag proves nothing + about whether the upload finished. A job keyed on ``PCAPKIT_TAG_EXISTS`` + skips itself on a retry after a partial release, and the run finishes green + because skipped is not failed -- so nothing in the UI says the release did + not happen. + + `Each job past version_check reads its own evidence, not a shared proxy`_ + above is what prevents it: ``tag``, ``pypi`` and ``conda`` each check whether + *their own* artefact is missing rather than whether the ``v*`` tag exists, so an incomplete release runs the jobs that did not finish instead of skipping them. A half-finished release now self-heals on the next ``workflow_run``-triggered attempt, or on re-running the workflow by hand -- see `Recovery`_ below. diff --git a/docs/source/contributing/workflows.rst b/docs/source/contributing/workflows.rst index 763eb969ad..1527cd8957 100644 --- a/docs/source/contributing/workflows.rst +++ b/docs/source/contributing/workflows.rst @@ -6,8 +6,7 @@ GitHub Actions Workflows The eight workflows under :file:`.github/workflows/` trigger each other, and the chain that results is not visible from any single file -- reading one ``on:`` block never shows what a *different* workflow's completion goes on - to start. This page is the repository-wide graph, requested on - `#897 `__. It does not + to start. This page is the repository-wide graph. It does not cover the release *pipeline* itself -- the job-by-job path from a version bump to a published package -- which :doc:`releasing` already documents in full; this page cross-references that rather than duplicating it. @@ -167,9 +166,8 @@ re-running the gate a second time. ``workflow_run`` edges ----------------------- -Four in total -- one more than the three named in `#897 -`__'s own description, -found by grepping every ``on:`` block rather than trusting that list: +Four in total, found by grepping every ``on:`` block rather than trusting a +hand-maintained list: * ``.github/workflows/cron-vendor.yml:14-16`` -- **Vendor Update** fires on completion of **Unit Tests**. diff --git a/docs/source/ext.rst b/docs/source/ext.rst index 5315f48f73..2d74fb352d 100644 --- a/docs/source/ext.rst +++ b/docs/source/ext.rst @@ -229,11 +229,11 @@ The following code snippet shows how to create a new protocol class: .. important:: - **Declare every construction keyword your protocol accepts.** Since #617, - building a protocol *through its constructor* with a keyword that no signature + **Declare every construction keyword your protocol accepts.** Building a + protocol *through its constructor* with a keyword that no signature declares raises :exc:`~pcapkit.utilities.exceptions.UnsupportedCall` rather than - discarding it, so a misspelling costs an exception instead of a silently wrong - field. The accepted set is read from :func:`inspect.signature` -- the union of every + discarding it silently, so a misspelling costs an exception instead of a + silently wrong field. The accepted set is read from :func:`inspect.signature` -- the union of every keyword-taking parameter of ``make``, ``read``, ``pack``, ``unpack``, ``__post_init__`` and ``__init__`` anywhere in the class's MRO -- which is wider than ``make`` alone because :meth:`ProtocolBase.__post_init__ @@ -280,8 +280,8 @@ The following code snippet shows how to create a new protocol class: is the idiom that reaches it, used by this package's own tests and by :meth:`HTTP.make ` to reach its versioned implementation. Covering that would mean interposing on every - ``make`` in the tree, which is a larger change than #617 and was deliberately - not made. Construct through the constructor to get the check. + ``make`` in the tree -- a larger change that was deliberately not made. + Construct through the constructor to get the check. .. note:: diff --git a/docs/source/pcapkit/const/ngap.rst b/docs/source/pcapkit/const/ngap.rst index cea51d75c7..d43df3f0a5 100644 --- a/docs/source/pcapkit/const/ngap.rst +++ b/docs/source/pcapkit/const/ngap.rst @@ -17,8 +17,7 @@ enumerations include: Both are automatically generated from |pycrate|_'s compiled NGAP specification rather than an IANA-style registry -- see -:mod:`pcapkit.vendor.ngap.procedure_code`'s module docstring for why, and -GitHub issue #880 for the ruling. +:mod:`pcapkit.vendor.ngap.procedure_code`'s module docstring for why. NGAP Elementary Procedure Codes =============================== diff --git a/docs/source/pcapkit/corekit/sentinels.rst b/docs/source/pcapkit/corekit/sentinels.rst index d92299283e..fe673bb861 100644 --- a/docs/source/pcapkit/corekit/sentinels.rst +++ b/docs/source/pcapkit/corekit/sentinels.rst @@ -8,13 +8,10 @@ module-level singleton sentinel this package defines for itself -- a value whose only job is to be recognised by identity (``value is SENTINEL``), so that it can never be confused with a value a caller might legitimately pass. -Each of the three below used to live beside the one class that consumed it -- -:class:`NullType` in :mod:`pcapkit.corekit.module`, :class:`NoValueType` in -:mod:`pcapkit.corekit.fields.field` and :class:`NoDefaultType` in -:mod:`pcapkit.corekit.enum` -- until GitHub issue #911 moved all four -definitions here, the private ``AbsentType``/``ABSENT`` included. Each -original module keeps a re-export, so every existing ``from import -`` keeps working unchanged. +All four are defined here. The three public ones are also re-exported by +:mod:`pcapkit.corekit.module`, :mod:`pcapkit.corekit.fields.field` and +:mod:`pcapkit.corekit.enum` respectively, so ``from import `` +resolves from either path. .. autoclass:: pcapkit.corekit.sentinels.NullType .. autodata:: pcapkit.corekit.sentinels.NULL @@ -29,16 +26,11 @@ original module keeps a re-export, so every existing ``from import .. note:: :class:`AbsentType` and :data:`ABSENT` are **private** -- never imported outside - :mod:`pcapkit.protocols.protocol`, and named in no module's ``__all__``. Until - GitHub issue #937, the leading underscore they carried (``_AbsentType``/ - ``_Absent``) hid them from Sphinx automatically, the way it hides every other - ``_``-prefixed name; dropping the underscore for SCREAMING_SNAKE consistency with - the other three sentinels (see :ref:`sentinel-convention`) means Sphinx would - otherwise document them as though they were public. They are documented below - instead, explicitly marked private, per the maintainer's ruling on #937: *"we can - change* ``_ABSENT`` *to* ``ABSENT`` *just document it as private type/class in the - documentation and not for public use is enough."* Neither is for use outside this - package. + :mod:`pcapkit.protocols.protocol`, and named in no module's ``__all__``. For + SCREAMING_SNAKE consistency with the other three sentinels (see + :ref:`sentinel-convention`), neither carries the leading underscore that would + otherwise hide it from Sphinx automatically, so both are documented below and + explicitly marked private. Neither is for use outside this package. .. autoclass:: pcapkit.corekit.sentinels.AbsentType .. autodata:: pcapkit.corekit.sentinels.ABSENT diff --git a/docs/source/pcapkit/foundation/engines/3rdparty.rst b/docs/source/pcapkit/foundation/engines/3rdparty.rst index ef99e55719..cc9acd6351 100644 --- a/docs/source/pcapkit/foundation/engines/3rdparty.rst +++ b/docs/source/pcapkit/foundation/engines/3rdparty.rst @@ -166,10 +166,9 @@ support, as is used by :class:`pcapkit.foundation.extraction.Extractor`. ``_PyLong_AsByteArray`` arity =============== =============================================================== - Upstream is unmaintained -- one doc-only commit since 1.3.0, and its Python - 3.12 issue (`pynetwork/pypcap#116 - `_) has been open and - uncommented since May 2024 -- so the cap is not expected to lift. Use + Upstream is unmaintained, and its Python 3.12 issue (`pynetwork/pypcap#116 + `_) remains open and + uncommented, so the cap is not expected to lift. Use :class:`~pcapkit.foundation.engines.pcap_ct.PCAP_CT` on 3.12 and newer. .. important:: diff --git a/docs/source/pcapkit/foundation/reassembly/ip/ipv4.rst b/docs/source/pcapkit/foundation/reassembly/ip/ipv4.rst index 22407f4090..fd5f3736de 100644 --- a/docs/source/pcapkit/foundation/reassembly/ip/ipv4.rst +++ b/docs/source/pcapkit/foundation/reassembly/ip/ipv4.rst @@ -109,9 +109,9 @@ Terminology overlapping fragment's disagreement itself -- "this procedure will use the more recently arrived copy in the data buffer" -- the opposite resolution from TCP's first-write-wins - (:rfc:`9293#section-3.10`, fixed for TCP by #443) -- so a contested + (:rfc:`9293#section-3.10`) -- so a contested range never leaves a hole on its own, and ``conflict`` is what lets - a caller tell a clean datagram from a contested one. See #477. + a caller tell a clean datagram from a contested one. reasm.ipv4.buffer Data structure for internal buffering when performing reassembly algorithms diff --git a/docs/source/pcapkit/foundation/reassembly/ip/ipv6.rst b/docs/source/pcapkit/foundation/reassembly/ip/ipv6.rst index 5146ff1b25..15194e91c9 100644 --- a/docs/source/pcapkit/foundation/reassembly/ip/ipv6.rst +++ b/docs/source/pcapkit/foundation/reassembly/ip/ipv6.rst @@ -59,8 +59,7 @@ Terminology does count it -- it is a header length, and the Fragment header is one of the extension headers it has walked -- so the adapters subtract it back off. All four adapters (``pcap``, ``pcapng``, ``dpkt`` and - ``scapy``) agree on the three fields; they used to report three - different values for ``tl`` alone, which is what #415 was about. + ``scapy``) agree on the three fields. .. note:: @@ -142,9 +141,9 @@ Terminology overlapping fragment's disagreement itself -- "this procedure will use the more recently arrived copy in the data buffer" -- the opposite resolution from TCP's first-write-wins - (:rfc:`9293#section-3.10`, fixed for TCP by #443) -- so a contested + (:rfc:`9293#section-3.10`) -- so a contested range never leaves a hole on its own, and ``conflict`` is what lets - a caller tell a clean datagram from a contested one. See #477. + a caller tell a clean datagram from a contested one. reasm.ipv6.buffer Data structure for internal buffering when performing reassembly algorithms diff --git a/docs/source/pcapkit/foundation/reassembly/tcp.rst b/docs/source/pcapkit/foundation/reassembly/tcp.rst index 61ec317137..ae331faed5 100644 --- a/docs/source/pcapkit/foundation/reassembly/tcp.rst +++ b/docs/source/pcapkit/foundation/reassembly/tcp.rst @@ -295,10 +295,9 @@ Terminology shared by every ACK in this dict, while each ACK's own ``raw`` is private to it, so a different ACK's segment closing a hole in ``hdl`` says nothing about whether *this* ACK has received anything at the - same sequence numbers -- consulting ``hdl`` for that question - previously discarded a fragment's own real bytes whenever a different - ACK bucket under the same buffer ID happened to cover the same range - first. + same sequence numbers -- consulting ``hdl`` for that question would + discard a fragment's own real bytes whenever a different ACK bucket + under the same buffer ID happens to cover the same range first. ``gap`` is kept in the same **absolute, inclusive sequence number** convention as ``conflict`` above (and as ``hdl``'s own hole diff --git a/docs/source/pcapkit/index.rst b/docs/source/pcapkit/index.rst index d7ce1afbeb..0de5a07020 100644 --- a/docs/source/pcapkit/index.rst +++ b/docs/source/pcapkit/index.rst @@ -62,8 +62,8 @@ Command Line Tool This module requires ``emoji`` package to be installed. -:mod:`pcapkit.__main__` was originally the module file of -|jspcapy|_, which is now deprecated and merged with :mod:`pcapkit`. +:mod:`pcapkit.__main__` provides the CLI, merged in from the now-deprecated +|jspcapy|_ project. .. |jspcapy| replace:: ``jspcapy`` .. _jspcapy: https://github.com/JarryShaw/jspcapy diff --git a/docs/source/pcapkit/protocols/internet/ipv6_ext.rst b/docs/source/pcapkit/protocols/internet/ipv6_ext.rst index 70f1b0bc2b..5da6cc37c3 100644 --- a/docs/source/pcapkit/protocols/internet/ipv6_ext.rst +++ b/docs/source/pcapkit/protocols/internet/ipv6_ext.rst @@ -5,7 +5,7 @@ IPv6_Ext - IPv6 Extension Header :mod:`pcapkit.protocols.internet.ipv6_ext` contains :class:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext` -only, which serves two roles at once (GitHub issue #917): it is the +only, which serves two roles at once: it is the shared **base class** of all eight IPv6 extension headers this package implements -- supplying them the ``extension``-mode contract, i.e. the guards that make :attr:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext.payload`, diff --git a/docs/source/pcapkit/protocols/misc/pcapng.rst b/docs/source/pcapkit/protocols/misc/pcapng.rst index 6b306d5360..71de1768ff 100644 --- a/docs/source/pcapkit/protocols/misc/pcapng.rst +++ b/docs/source/pcapkit/protocols/misc/pcapng.rst @@ -197,11 +197,11 @@ Auxiliary Data :undoc-members: :show-inheritance: -:class:`TLSKeyLabel ` moved to -:mod:`pcapkit.const.pcapng.tls_key_label` (GitHub issue #886), generated the -same way as its :mod:`pcapkit.const.pcapng` siblings since :rfc:`9850#section-4.2` -makes it an IANA registry rather than a hand-picked helper enum. This module -still re-exports it under its own name, so +:class:`TLSKeyLabel ` lives in +:mod:`pcapkit.const.pcapng.tls_key_label`, generated the same way as its +:mod:`pcapkit.const.pcapng` siblings since :rfc:`9850#section-4.2` makes it an +IANA registry rather than a hand-picked helper enum. This module still +re-exports it under its own name, so ``from pcapkit.protocols.misc.pcapng import TLSKeyLabel`` keeps working. .. autoclass:: pcapkit.protocols.misc.pcapng.WireGuardKeyLabel diff --git a/docs/source/pcapkit/vendor/ipx.rst b/docs/source/pcapkit/vendor/ipx.rst index 8cb0fd0b85..078ce8ec52 100644 --- a/docs/source/pcapkit/vendor/ipx.rst +++ b/docs/source/pcapkit/vendor/ipx.rst @@ -37,13 +37,13 @@ which is automatically generating :class:`pcapkit.const.ipx.socket.Socket`. .. note:: - This crawler no longer crawls. The table it used to scrape was deleted from - the Wikipedia article on 2026-08-25, and the registry itself is closed, so - the data is now maintained by hand in the ``DATA`` and ``RANGES`` mappings of + This crawler no longer crawls. The table was removed from the Wikipedia + article, and the registry itself is closed, so the data is now maintained + by hand in the ``DATA`` and ``RANGES`` mappings of :mod:`pcapkit.vendor.ipx.socket`, and the class defines no ``LINK``. The footnote below points at the last revision that still carried the table -- what the hand-maintained registry was transcribed from, not a page the - crawler fetches. See #507. + crawler fetches. .. autoclass:: pcapkit.vendor.ipx.socket.Socket :members: FLAG diff --git a/docs/source/pcapkit/vendor/ngap.rst b/docs/source/pcapkit/vendor/ngap.rst index 309ec9aaa1..2ec033c678 100644 --- a/docs/source/pcapkit/vendor/ngap.rst +++ b/docs/source/pcapkit/vendor/ngap.rst @@ -17,7 +17,7 @@ vendor crawlers include: Both source the assignment from |pycrate|_'s already-installed, compiled NGAP specification rather than fetching a network registry -- see the module -docstring below for why, and GitHub issue #880 for the ruling. +docstring below for why. NGAP Elementary Procedure Codes =============================== diff --git a/docs/source/pcapkit/vendor/pcapng.rst b/docs/source/pcapkit/vendor/pcapng.rst index 6a6911367e..0483f4d916 100644 --- a/docs/source/pcapkit/vendor/pcapng.rst +++ b/docs/source/pcapkit/vendor/pcapng.rst @@ -33,14 +33,11 @@ vendor crawlers include: :class:`BlockType `, :class:`OptionType ` and :class:`RecordType ` -- all read - revision ``-03`` of the draft, as each one's ``LINK`` below shows. They used to - read ``https://www.ietf.org/staging/draft-tuexen-opsawg-pcapng-02.html``, which - is dead: measured 2026-09-19 as a 404 under any User-Agent. The revision number - was wrong as well as the path -- ``-02`` renders its registries as ASCII art - inside ``
`` and carries no registry ```` at all, so the ``table-1``
-   through ``table-10`` ids the three crawlers select on first exist in ``-03``,
-   where the registries became real tables. The footnotes below point at ``-03``
-   for the same reason. See #518.
+   revision ``-03`` of the draft, as each one's ``LINK`` below shows. Revision
+   ``-02`` renders its registries as ASCII art inside ``
`` and carries no
+   registry ``
`` at all, so the ``table-1`` through ``table-10`` ids the
+   three crawlers select on exist only in ``-03``, where the registries are real
+   tables. The footnotes below point at ``-03`` for the same reason.
 
 Block Types
 ===========