Skip to content

Commit 5d86fcb

Browse files
committed
docs(releasing): fix the review findings on the non-API docs pass (#1103)
- releasing: only tag, pypi and conda open with !cancelled() and require version_check to succeed; github does neither - releasing: gh release upload's deliberate failures get a subject - workflows: the workflow_run edge list gets a subject; "the gating jobs" are what a docs-only pull request may skip - extension-header-subclassing: "every extension header" has an antecedent - index: Test Results footnotes annotate only the empty cells; the PyShark requirements line is a sentence - pep: the AppType bullet names the ports bound in TCP/UDP __proto__; the ESP structural-notes line is a sentence Refs #1103
1 parent de22a52 commit 5d86fcb

5 files changed

Lines changed: 40 additions & 40 deletions

File tree

‎docs/source/contributing/conventions/extension-header-subclassing.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,7 @@ Explicit Base Declarations
115115

116116
Name the second base **explicitly**, even though it is already in the MRO.
117117
:class:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext` derives
118-
:class:`~pcapkit.protocols.internet.internet.Internet`, so every one of them
118+
:class:`~pcapkit.protocols.internet.internet.Internet`, so every extension header
119119
reaches ``Internet`` transitively and an ``__mro__`` check cannot tell the two groups
120120
apart. The declaration is the only place the classification exists, which is why
121121
``tests/protocols/internet/test_ipv6_ext_unit.py`` pins it against ``__bases__``:

‎docs/source/contributing/pep.rst‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -119,8 +119,8 @@ either, and are the one item on this list that is not simply a table entry: the
119119
high-order 32 bits are never transmitted, so recovering them is stateful, and
120120
they widen both the ICV coverage and the AEAD associated data.
121121

122-
Some structural notes for anyone starting. Adding an integrity algorithm that is
123-
not an HMAC needs more than a row --
122+
Some structural notes matter to anyone starting. Adding an integrity algorithm
123+
that is not an HMAC needs more than a row --
124124
:class:`~pcapkit.protocols.internet.esp.IntegritySuite` records the digest as
125125
the name of a :mod:`hashlib` constructor, which AES-XCBC and AES-CMAC are not.
126126
And :func:`~pcapkit.protocols.internet.esp.load_cryptography` imports only the
@@ -271,9 +271,11 @@ complaint and yields nothing useful.
271271
* :class:`~pcapkit.const.reg.ethertype.EtherType` -- the values in
272272
:attr:`Link.__proto__ <pcapkit.protocols.link.link.Link.__proto__>`: ARP,
273273
RARP, IPv4, IPv6, IPX and both VLAN tags.
274-
* :class:`~pcapkit.const.reg.apptype.apptype.AppType`, a registry carrying every
275-
IANA service name -- TCP 20 to FTP-DATA and 21 to FTP, port 80 and 8080 to HTTP
276-
on both TCP and UDP, and UDP 1701 to L2TP.
274+
* :class:`~pcapkit.const.reg.apptype.apptype.AppType` -- the ports bound in
275+
:attr:`TCP.__proto__ <pcapkit.protocols.transport.tcp.TCP.__proto__>` and
276+
:attr:`UDP.__proto__ <pcapkit.protocols.transport.udp.UDP.__proto__>`, out of
277+
a registry carrying every IANA service name: TCP 20 to FTP-DATA and 21 to FTP,
278+
ports 80 and 8080 to HTTP on both TCP and UDP, and UDP 1701 to L2TP.
277279
* :class:`~pcapkit.const.sctp.payload_protocol_identifier.PayloadProtocolIdentifier`
278280
-- the values in :attr:`SCTP.__proto__
279281
<pcapkit.protocols.transport.sctp.SCTP.__proto__>`: PPIDs 60 and 66, each to

‎docs/source/contributing/releasing.rst‎

Lines changed: 24 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -180,12 +180,13 @@ the default branch, and ``tag`` pulled ``main`` before tagging.
180180
again (``--clobber``). ``conda``'s upload is not gated on ``check_leg``, so a
181181
leg whose Anaconda upload landed but whose GitHub upload failed still gets
182182
its asset on a re-run.
183-
* Where it fails, it differs from the action deliberately. With no release for the tag, the
184-
upload fails with ``gh``'s "release not found", where the action made one,
185-
with no notes and ``target_commitish`` unset (``src/github.ts:617-628,1026``),
186-
which Create a release defaults to "the repository's default branch"; the
187-
release is ``github``'s to make, at the run's commit. A file pattern matching
188-
nothing exits 1 with ``::error title=Nothing to upload``, where the action,
183+
* ``gh release upload`` also fails, deliberately, where the action did not.
184+
With no release for the tag, the upload fails with ``gh``'s
185+
"release not found", where the action made one, with no notes and
186+
``target_commitish`` unset (``src/github.ts:617-628,1026``), which Create a
187+
release defaults to "the repository's default branch"; the release is
188+
``github``'s to make, at the run's commit. A file pattern matching nothing
189+
exits 1 with ``::error title=Nothing to upload``, where the action,
189190
``fail_on_unmatched_files`` unset, only warned (``src/run.ts:15-20``) and
190191
published the release without that file.
191192

@@ -391,23 +392,23 @@ this run, it *skipped*.
391392
``cron-vendor.yml``, ``deploy-pages.yml`` and ``cron-conda.yml`` each open
392393
with ``!cancelled() && needs.unit-tests.result != 'failure'`` so that a
393394
skipped gate does not cascade-skip them, while an outright failure or a
394-
genuine run cancellation still does. The publishing jobs here are stricter about
395-
their *publishing* predecessors -- ``github``, and for ``conda`` also ``tag``:
396-
``!cancelled() && (needs.<job>.result == 'success' || needs.<job>.result ==
397-
'skipped')``, not ``!= 'failure'``. The two spellings differ only when a
398-
predecessor's own result is ``cancelled``, which ``!= 'failure'`` still admits
399-
and the equality pair does not. Concretely: if ``tag`` is cancelled while the
400-
run itself is not, ``!= 'failure'`` would let ``conda`` proceed into its
401-
check that ``conda-<version>+0`` names this run's commit, a tag ``tag`` never
402-
pushed, trading a clean skip for a failed step; the equality pair skips
403-
``conda`` outright instead.
404-
405-
``version_check`` is the exception, and deliberately so: each of them requires
406-
``needs.version_check.result == 'success'`` with no ``|| 'skipped'``. It
407-
produces the evidence the gates read, so a skipped or cancelled
408-
``version_check`` leaves them nothing to decide on. ``unit-tests`` is held to
409-
the same bar for a different reason: it is the release test gate, and it skips
410-
when nothing is publishable
395+
genuine run cancellation still does. ``tag``, ``pypi`` and ``conda`` are
396+
stricter about their *publishing* predecessors -- ``github``, and for
397+
``conda`` also ``tag``: ``!cancelled() && (needs.<job>.result == 'success' ||
398+
needs.<job>.result == 'skipped')``, not ``!= 'failure'``. The two spellings
399+
differ only when a predecessor's own result is ``cancelled``, which
400+
``!= 'failure'`` still admits and the equality pair does not. Concretely: if
401+
``tag`` is cancelled while the run itself is not, ``!= 'failure'`` would let
402+
``conda`` proceed into its check that ``conda-<version>+0`` names this run's
403+
commit, a tag ``tag`` never pushed, trading a clean skip for a failed step; the
404+
equality pair skips ``conda`` outright instead.
405+
406+
``version_check`` is the exception, and deliberately so: ``tag``, ``pypi`` and
407+
``conda`` each require ``needs.version_check.result == 'success'`` with no
408+
``|| 'skipped'``. It produces the evidence the gates read, so a skipped or
409+
cancelled ``version_check`` leaves them nothing to decide on. ``unit-tests`` is
410+
held to the same bar for a different reason: it is the release test gate, and
411+
it skips when nothing is publishable
411412
(`#1052 <https://github.com/JarryShaw/PyPCAPKit/issues/1052>`__), so accepting
412413
``skipped`` there would publish untested. ``github`` names it in ``needs:`` instead and relies on the implicit
413414
``success()``. The gate's own ``if:`` is the union of the publishers'

‎docs/source/contributing/workflows.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -244,8 +244,8 @@ rather than the event, so its gate can run whichever way the run was raised, onc
244244
``workflow_run`` Edges
245245
----------------------
246246

247-
Found by grepping every ``on:`` block rather than trusting a hand-maintained
248-
list:
247+
These edges come from grepping every ``on:`` block rather than from a
248+
hand-maintained list:
249249

250250
* ``.github/workflows/cron-vendor.yml:14-16`` -- **Vendor Update** fires on
251251
completion of **Unit Tests**.
@@ -671,7 +671,7 @@ for the docs-only path -- and checks each result explicitly
671671
(``unit-tests.yml:1936-1990``). Rulesets match check names literally, with no
672672
wildcard, so requiring the matrix cells one by one would mean editing the
673673
ruleset whenever a matrix changes; the aggregate keeps the required list fixed.
674-
It accepts those legs as ``skipped`` only on a docs-only pull request, where
674+
It accepts the gating jobs as ``skipped`` only on a docs-only pull request, where
675675
``project-tests`` -- every test that reads ``docs/`` or Markdown -- must pass
676676
instead. The ``Compat`` legs stay required separately because they come from
677677
``python-compatibility.yml``, and a job cannot ``needs:`` a job in another

‎docs/source/index.rst‎

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -220,23 +220,20 @@ Engine 3.10 3.11 3.12 3.13 3.14
220220
``pypcapfile`` [1]_ 0.0133 0.0093 -- -- --
221221
``dpkt`` 0.0163 0.0113 0.0118 0.0117 0.0125
222222
``pypcap`` [2]_ 0.0289 0.0212 -- -- --
223-
``pcap_ct`` [3]_ 0.0364 0.0320 0.0366 0.0322 0.0396
223+
``pcap_ct`` 0.0364 0.0320 0.0366 0.0322 0.0396
224224
``scapy`` 0.1082 0.0822 0.0877 0.0832 0.0967
225225
``pcapkit`` 0.2342 0.1906 0.1985 0.1920 0.2392
226-
``pyshark`` [4]_ 18.8158 18.7852 19.2694 20.3751 --
226+
``pyshark`` [3]_ 18.8158 18.7852 19.2694 20.3751 --
227227
=================== ======= ======= ======= ======= =======
228228

229229
The unavailable cells were attempted. They are not zeroes and must not be
230230
compared with a measured row.
231231

232232
.. [1] `PyPCAPFile`_ 0.12.0 imports :mod:`imp`, which Python removed in 3.12.
233233
234-
.. [2] `PyPCAP`_ 1.3.0 is unsupported on Python 3.12+, and its build does not
235-
search Homebrew's libpcap library prefix.
234+
.. [2] `PyPCAP`_ 1.3.0 is unsupported on Python 3.12+.
236235
237-
.. [3] `pcap-ct`_ and `libpcap`_ are published only as pre-releases.
238-
239-
.. [4] `PyShark`_ 0.6 cannot create the implicit event loop it expects on Python
236+
.. [3] `PyShark`_ 0.6 cannot create the implicit event loop it expects on Python
240237
3.14; it ran on 3.10--3.13.
241238
242239
Installation
@@ -376,7 +373,7 @@ below is also enforced in code, by the
376373
preflight described under `Engine Comparison`_.
377374

378375
:class:`~pcapkit.foundation.engines.pyshark.PyShark`
379-
Requirements, none of them visible to an import: the package imports
376+
None of its requirements is visible to an import: the package imports
380377
cleanly and then fails when used.
381378

382379
- Drives Wireshark's :program:`tshark` binary. It need not be on ``PATH``:

0 commit comments

Comments
 (0)