From 7f357aa01637fb58c3dfc8600cfcb1e37648654b Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Thu, 15 Oct 2026 18:49:28 -0400 Subject: [PATCH] docs(repo): second whole-repo pass over repo-level files (#1103) Accuracy -- claims that no longer matched the tree: - Six crawlers import bs4 at module scope, not seven (pyproject x2, cron-vendor.yml); cron-vendor installs .[all,vendor], not .[all]. - benchmark: a default run spawns 3,000 tshark processes per environment, not six thousand (README, benchmark.py). - options.py: IPv4 and HIP have registries; make_samples.py: in.pcap and dhcp.pcapng are tracked; the PyYAML note no longer lists four of eleven. - Re-measured: ci-timing calls (690) and workflow list, bump_version's version-commit counts, verdict_covers_checkout's bot commits, and MANIFEST.in's sdist note (no stale entry count or "four lines"). - Stale line references: raw.py, arp.py, engines/pcapng.py, pyproject.toml. Citations: PR #434 and PR #853 cited as their issues, #429 and #851. Timed context: about 20 "now", "since #NNN", "no longer", "as before", "until #1674" and "lately" phrases across the workflows, util/ and examples/. Comments and docstrings only: every changed .py keeps an identical AST with string expressions blanked; YAML and TOML load identically, except comment-only lines in one cron-vendor.yml run: block. tests/project passes. Refs #1103 --- .github/workflows/ci-timing.yml | 7 ++++--- .github/workflows/create-release.yml | 16 ++++++++-------- .github/workflows/cron-vendor.yml | 8 ++++---- .github/workflows/python-compatibility.yml | 2 +- .github/workflows/unit-tests.yml | 14 +++++++------- MANIFEST.in | 6 +++--- examples/benchmark/README.md | 6 +++--- examples/benchmark/benchmark.py | 2 +- examples/benchmark/python-images.txt | 4 ++-- examples/generators/dispatch.py | 6 +++--- examples/generators/make_samples.py | 10 +++++----- examples/generators/options.py | 14 +++++++------- pyproject.toml | 11 +++++------ util/bump_version.py | 6 +++--- util/changelog_md.py | 13 ++++++------- util/pyshark_encap_map.py | 4 ++-- util/run_unittest_leg.py | 9 +++++---- util/vendor_code_changed.py | 9 ++++----- util/verdict_covers_checkout.py | 2 +- 19 files changed, 74 insertions(+), 75 deletions(-) diff --git a/.github/workflows/ci-timing.yml b/.github/workflows/ci-timing.yml index 2e702434d9..58c2d58544 100644 --- a/.github/workflows/ci-timing.yml +++ b/.github/workflows/ci-timing.yml @@ -1,8 +1,9 @@ name: CI Timing # The periodic CI-duration review #1538 asked for. util/ci_timing.py reads the -# last week of Unit Tests, Compat, Lint, CodeQL and Pages runs through the API, -# writes a report to the job summary and to an artifact, and fails the run when a +# last week of Unit Tests, Compat, Lint, CodeQL, Pages and Experimental Tests +# runs through the API, writes a report to the job summary and to an artifact, +# and fails the run when a # HARD threshold fires (status 1; 2 and 3 are an unreadable API and a crash, each # annotated as such). GitHub emails a scheduled workflow's failures to whoever # last edited its cron line, so the owner hears about it with no `issues: write`. @@ -29,7 +30,7 @@ on: # Read-only: the runs, jobs and artifacts need `actions: read`, the workflow # files at each run's sha need `contents: read`. GITHUB_TOKEN allows 1,000 API -# requests an hour per repository; a default run uses about 600. +# requests an hour per repository; a default run uses about 690. permissions: actions: read contents: read diff --git a/.github/workflows/create-release.yml b/.github/workflows/create-release.yml index 528582d535..144887ea36 100644 --- a/.github/workflows/create-release.yml +++ b/.github/workflows/create-release.yml @@ -69,7 +69,7 @@ concurrency: # an unintended publish -- a version number it has accepted cannot be reused, and # ``skip-existing: true`` below means a re-upload then *succeeds* having published # nothing, so the number the intended release wanted is gone regardless. ``github`` -# and ``tag`` were split on the same principle: since #1634 ``github`` spends a +# and ``tag`` were split on the same principle (#1634): ``github`` spends a # token of the release App, minted in the job from ``github-release``'s secret # and revoked when it ends (the run's ``GITHUB_TOKEN`` while no App is set up), # whereas ``tag`` spends a long-lived PAT and a deploy key to write to the @@ -266,7 +266,7 @@ jobs: version_check: name: Check Version runs-on: ubuntu-latest - # The outermost gate since #1052, moved here from ``unit-tests``: a + # The outermost gate, moved here from ``unit-tests`` by #1052: a # ``workflow_run`` trigger proceeds only when the Vendor Update run that # triggered it concluded ``success``, and a tag push always proceeds. This # job is read-only -- it installs the package and reads three public @@ -598,13 +598,13 @@ jobs: name: GitHub Release runs-on: ubuntu-latest # Gated: publishes the Release, and creates the ``v*`` tag -- at - # ``github.sha`` since #1634 -- that every job below then verifies before - # publishing under it. Since #887 this is the release's only approval -- + # ``github.sha`` (#1634) -- that every job below then verifies before + # publishing under it. This is the release's only approval (#887) -- # see the note above ``jobs:``. Still gated on ``PCAPKIT_TAG_EXISTS``, # unlike the three jobs below it: the tag that output answers for is this # job's own artefact, not a proxy for someone else's -- see the #888 note - # above ``jobs:``. ``unit-tests`` is listed since #1052, when the gate stopped - # preceding ``version_check``; this ``if:`` calls no status-check function, + # above ``jobs:``. ``unit-tests`` is listed because the gate follows + # ``version_check`` (#1052); this ``if:`` calls no status-check function, # so the implicit ``success()`` requires the gate to have passed. The # release App's private key is a ``github-release`` environment secret, so # no job reads it before this approval, and no other job reads it at all. @@ -1495,8 +1495,8 @@ jobs: # why, in one place, regardless of which upstream job or gate is what made it # release nothing. ``version_check`` can skip (a ``workflow_run`` whose Vendor # Update did not conclude ``success``) before any evidence output the jobs - # above rely on even exists, and ``unit-tests`` can fail or -- since #1052 -- - # skip because that evidence says nothing is left to publish, so this job + # above rely on even exists, and ``unit-tests`` can fail, or skip (#1052) + # because that evidence says nothing is left to publish, so this job # cannot simply read those outputs the way # ``tag``/``pypi``/``conda`` do -- it has to run unconditionally and # reconstruct what happened from ``needs.*.result`` and the trigger context diff --git a/.github/workflows/cron-vendor.yml b/.github/workflows/cron-vendor.yml index a7d5f79d9c..62d55de9f3 100644 --- a/.github/workflows/cron-vendor.yml +++ b/.github/workflows/cron-vendor.yml @@ -163,12 +163,12 @@ jobs: python -m pip install -U pip setuptools wheel packaging python -m pip install -U isort - # `all` carries `pycrate` since #910 (a core addon there now, see its - # own comment in pyproject.toml), but not `requests`/`beautifulsoup4` - # any more -- #910 moved those to the `dev` extra instead, which is + # `all` carries `pycrate`, a core addon under #910 (see its + # own comment in pyproject.toml), but not `requests`/`beautifulsoup4`: + # #910 moved those to the `dev` extra instead, which is # for the toolchain rather than for a vendor crawl. `vendor` is # installed alongside `all` for those two: `pcapkit-vendor` below - # regenerates every crawler with no target given, and seven of them + # regenerates every crawler with no target given, and six of them # import `bs4` at module scope while `pcapkit.vendor.default` imports # `requests` the same way (#507). See the `vendor` extra's own # comment in pyproject.toml for the full reasoning. diff --git a/.github/workflows/python-compatibility.yml b/.github/workflows/python-compatibility.yml index 0e0f31f4a5..63cbfaf0d2 100644 --- a/.github/workflows/python-compatibility.yml +++ b/.github/workflows/python-compatibility.yml @@ -85,7 +85,7 @@ jobs: # The install needs this leg's interpreter, and the check below needs the # install, as in unit-tests.yml's `test` job: on a KTLO leg a failed step - # no longer stops the job, so each one waits on the `outcome` it needs. + # does not stop the job, so each one waits on the `outcome` it needs. - name: Install package id: install if: ${{ steps.python.outcome == 'success' }} diff --git a/.github/workflows/unit-tests.yml b/.github/workflows/unit-tests.yml index f99b1abe7a..c50dcca29f 100644 --- a/.github/workflows/unit-tests.yml +++ b/.github/workflows/unit-tests.yml @@ -157,7 +157,7 @@ jobs: # 7 of the 10 HAS_PYPCAPFILE-gated methods this comment used to count # into failures, against a real bug in pcapkit/toolkit/pypcapfile.py's # handling of pypcapfile 0.12.0's `IP.src`/`IP.dst`. #743 and #746 fixed - # that bug, and #751 gave the now-safe extra a home: the dedicated + # that bug, and #751 gave the extra a home: the dedicated # `engine-tests` and `pypcap-parity` jobs below install it (15 # HAS_PYPCAPFILE-gated methods between them), deliberately apart from # this job rather than added to it -- see either job's own comment for @@ -489,7 +489,7 @@ jobs: # PyPCAPFile is NOT added here either, even though this job's selection # also reaches test_new_engine_parity_runtime.py's 6 HAS_PYPCAPFILE # methods -- see the `test` job's comment above for the bug that used to - # make installing it here a regression, now fixed by #743/#746. #751's + # make installing it here a regression, fixed by #743/#746. #751's # `pypcap-parity` job below covers those 6 methods instead, on the same # fixture-tier selection as this job but in a venv of its own. # @@ -1111,7 +1111,7 @@ jobs: # instruction was "try to build and if the CI is not a good suit, then we # ripe it". This job is that attempt: a C toolchain plus libpcap headers, on # the two Python versions its own marker allows - # ("pypcap; python_version < '3.12'", pyproject.toml:157). If a clean run of + # ("pypcap; python_version < '3.12'", pyproject.toml:168). If a clean run of # this job's install step goes red -- not a flake -- the fix is deleting this # job and returning HAS_PYPCAP to # tests/_dependency_gates.DEPENDENCY_GATE_EXCLUSIONS with that run linked as @@ -1428,8 +1428,8 @@ jobs: # #981's own reproduction needs, since the defect is an earlier module # polluting a later one. Running the whole suite in one process is not an # option (it OOMs at 29 GB on the machine this was diagnosed on); a matrix - # of one leg per top-level directory (protocols, since #1029, being two - # cells) is the affordable approximation, and it + # of one leg per top-level directory (protocols being two cells, #1029) + # is the affordable approximation, and it # is sized for wall time rather than for memory. Peak RSS was measured for # the three cheapest legs only -- cli 152 MiB, dumpkit 237 MiB, interface # 305 MiB (resource.getrusage on RUSAGE_CHILDREN, this venv) -- leaving the @@ -1439,7 +1439,7 @@ jobs: # 70s, protocols 847s (before the #1029 split), toolkit 97s, utilities 42s, # vendor 104s, one leg per # matrix cell -- see `timeout-minutes` below for why the job-level budget is - # no longer 20. + # 45 rather than 20. # # GitHub issue #1029: the protocols cell measured 30.4 minutes on a CI # runner against this job's 45-minute cap (#1029 measured the next slowest @@ -1798,7 +1798,7 @@ jobs: # above, which each cover only the subset their own selection reaches. # PyPCAPFile is deliberately NOT added here -- see the `test` job's # comment above for the bug that used to make installing it a - # regression, now fixed by #743/#746. This job runs on `latest` only, where + # regression, fixed by #743/#746. This job runs on `latest` only, where # PyPCAPFile's marker resolves to nothing regardless, so adding it here # would be a no-op that misleadingly suggests the extra is exercised by # `gate`; #751's `engine-tests` and `pypcap-parity` jobs cover it for diff --git a/MANIFEST.in b/MANIFEST.in index 75f7cc0e79..88b9abc61c 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -16,9 +16,9 @@ prune temp # file mentions them, so neither line is load-bearing. An earlier version of this # comment claimed the opposite -- that ``include README.md`` was "the only thing # that puts it in an sdist" and that an sdist without it "cannot be installed at -# all" -- and both halves are false. Measured by deleting these four lines and the -# two below them and rebuilding from a clean tree: the ``tar tzf`` listing is -# identical, 861 entries either way with an empty ``diff``, and the resulting sdist +# all" -- and both halves are false. Measured by deleting the two ``include`` +# lines below and rebuilding from a clean tree: the ``tar tzf`` listing is +# identical either way, with an empty ``diff``, and the resulting sdist # installs with exit 0. ``README.md``, ``LICENSE``, ``CHANGELOG.md`` and # ``CITATION.cff`` are all still in it. # diff --git a/examples/benchmark/README.md b/examples/benchmark/README.md index 267d2d214b..102e7081dc 100644 --- a/examples/benchmark/README.md +++ b/examples/benchmark/README.md @@ -126,8 +126,8 @@ never as a zero. ## One flaky engine must not cost the others their rows This is not hypothetical; it is what the first full run of this harness did. -`pyshark` spawns a `tshark` process per extraction, so a default run spawns **six -thousand** of them, and one of them died -- `TSharkCrashException ... retcode: 255`, +`pyshark` spawns a `tshark` process per extraction, so a default run spawns **three +thousand** of them per environment, and one of them died -- `TSharkCrashException ... retcode: 255`, on the third pass. The exception propagated, `benchmark.py` exited, no JSON was written, and the run produced **no table at all**. Six working engines went unreported because the seventh hiccupped once. @@ -397,7 +397,7 @@ self-tests below. ## Python 3.15 Opt-in, and allowed to fail -- the benchmark's own choice, not CI's: the repository's CI -has run 3.15 as a blocking, supported leg since #1633. There is no released +runs 3.15 as a blocking, supported leg (#1633). There is no released `python:3.15-slim-bookworm`; the pins file names a `3.15-rc` digest, which freezes one particular release candidate and will name an older one as time passes. Measure it with: diff --git a/examples/benchmark/benchmark.py b/examples/benchmark/benchmark.py index ffb6f0d87c..55a6b80c04 100644 --- a/examples/benchmark/benchmark.py +++ b/examples/benchmark/benchmark.py @@ -481,7 +481,7 @@ def measure(engine: 'str', capture: 'str', rounds: 'int', A small number of failed extractions is tolerated, and this is not fastidiousness. ``pyshark`` spawns a :program:`tshark` process per extraction, - so a default run spawns six thousand of them, and measured here: one of them + so a default run spawns three thousand of them, and measured here: one of them crashed with ``TSharkCrashException ... retcode: 255`` partway through the third pass and took the entire run with it -- six working engines went unreported because the seventh hiccupped once. A crashed extraction is a diff --git a/examples/benchmark/python-images.txt b/examples/benchmark/python-images.txt index aa87302db4..fe9fff93d8 100644 --- a/examples/benchmark/python-images.txt +++ b/examples/benchmark/python-images.txt @@ -60,8 +60,8 @@ # `3.15-rc-slim-bookworm` is a release candidate and the tag moves with every rc, so # the digest below freezes one particular candidate and will name an older rc as # time passes -- bump it deliberately, or drop the row when 3.15 ships. Opt-in is -# this file's own tier, not CI's: the repository's CI has run 3.15 as a blocking, -# supported leg since #1633. `run.sh --pythons ...,3.15` measures it, a plain +# this file's own tier, not CI's: the repository's CI runs 3.15 as a blocking, +# supported leg (#1633). `run.sh --pythons ...,3.15` measures it, a plain # `run.sh` does not, and a # version that cannot be built is reported as a missing column with the reason # rather than dropped. diff --git a/examples/generators/dispatch.py b/examples/generators/dispatch.py index 903578867c..aa907e9078 100644 --- a/examples/generators/dispatch.py +++ b/examples/generators/dispatch.py @@ -298,7 +298,7 @@ def _link_payload(code: 'int') -> 'bytes': from pcapkit.protocols.application.rarp import RARP # ARP/RARP/InARP/DRARP all report their alias from the wire ``oper`` - # field rather than from the dispatching EtherType (link/arp.py:176-190 + # field rather than from the dispatching EtherType (link/arp.py:191-202 # per #496), so ``oper`` has to land in the RARP range (3, 4) or this # would silently probe ARP instead while still "passing". return bytes(RARP(oper=3)) @@ -772,7 +772,7 @@ class Outcome(NamedTuple): #: renamed-on-the-wire class (RARP reporting itself as ``'ARP'``) from a #: wrong one -- but wrong here, because :class:`~pcapkit.protocols.misc.raw.Raw` #: itself constructs with ``alias=`` set to the *dispatching* code's own - #: name (pcapkit/protocols/misc/raw.py:144), so a mis-pointed registry + #: name (pcapkit/protocols/misc/raw.py:152), so a mis-pointed registry #: entry still renders its original code's name and would satisfy the #: string check while no instance of the pinned class exists anywhere in #: the chain. @@ -879,7 +879,7 @@ def probe(case: 'Case') -> 'Outcome': # some ``oper`` values, and is still the RARP class), but it is exactly # the loophole that let a mis-pointed registry entry through here: several # dissectors -- Raw chief among them, in - # pcapkit/protocols/misc/raw.py:144 -- construct with ``alias=`` set to + # pcapkit/protocols/misc/raw.py:152 -- construct with ``alias=`` set to # the *dispatching* code's own name, so a code named ``AH`` retargeted at # Raw still renders as ``'...:AH'`` and still satisfies ``AH in # protochain`` on the string alone, even though no AH instance exists diff --git a/examples/generators/make_samples.py b/examples/generators/make_samples.py index 0d2785c1cb..19c1c707b7 100644 --- a/examples/generators/make_samples.py +++ b/examples/generators/make_samples.py @@ -1,11 +1,11 @@ # -*- coding: utf-8 -*- """Regenerate the sample captures used by the test suite and the examples. -The captures under ``examples/captures/`` are not tracked in git (see -``.gitignore``), yet the runtime, regression and integration tests read them and -pin their contents, as do the demonstration scripts in -``examples/legacy_smoke/``. This script rebuilds the whole set, so a fresh clone -can run ``pytest`` without any ignore flags: +The captures under ``examples/captures/`` are not tracked in git, apart from the +two inputs ``in.pcap`` and ``dhcp.pcapng`` (see ``.gitignore``), yet the runtime, +regression and integration tests read them and pin their contents, as do the +demonstration scripts in ``examples/legacy_smoke/``. This script rebuilds the +generated captures, so a fresh clone can run ``pytest`` without any ignore flags: .. code-block:: shell diff --git a/examples/generators/options.py b/examples/generators/options.py index c98ba1c682..eaa6adfa01 100644 --- a/examples/generators/options.py +++ b/examples/generators/options.py @@ -57,10 +57,10 @@ :meth:`ProtocolBase._lookup_registry ` instead. -IPv4 and HIP have no such registry yet -- they dispatch on the attribute name -``_make_opt_${name}`` / ``_make_param_${name}`` -- so for those two the source -of truth is the enumeration crossed with the presence of the handler, which is -what :func:`_named_registry` builds. +IPv4 and HIP are read through :func:`_named_registry`, which returns the +protocol's own registry and, for a protocol without one, falls back to the +enumeration crossed with the presence of the ``_make_opt_${name}`` / +``_make_param_${name}`` handler. Determinism ----------- @@ -372,8 +372,8 @@ def _named_registry(owner: 'type', enum: 'Any', prefix: 'str', enumeration crossed with the presence of the handler, which is what this builds when the registry is absent. - GitHub pull request #434 gave both of them a real registry, so the fallback - is no longer taken for either -- it is kept because it costs nothing and is + Both of them have a real registry (#429), so the fallback is not taken + for either -- it is kept because it costs nothing and is the only thing that would notice a protocol added tomorrow without one. Both shapes are a :class:`collections.defaultdict`, so :func:`cases` and :func:`handler` cannot tell which one they were given -- and in particular @@ -1284,7 +1284,7 @@ def _pcapng_context() -> 'tuple[Any, Any]': # ``Protocol.info`` is annotated as the generic data model for the protocol, # so a checker cannot see that a Section Header Block's is the one ``Context`` # wants. The engine does exactly this, at - # pcapkit/foundation/engines/pcapng.py:148. + # pcapkit/foundation/engines/pcapng.py:181. section_info = section.info # type: Any context = Context(section_info) interface = PCAPNG(num=1, sct=1, ctx=context, diff --git a/pyproject.toml b/pyproject.toml index e60b88a32f..6a20fc2d09 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -223,7 +223,7 @@ PyPCAPFile = [ "pypcapfile; python_version < '3.12'" ] # for developers -- installs pcapkit.vendor's crawlers, run via # `pcapkit-vendor` to regenerate pcapkit.const. Includes ``pycrate`` so # pcapkit.vendor.ngap's two crawlers (#880) can run, and ``requests``/ -# ``beautifulsoup4`` for the seven crawlers that import them at module scope +# ``beautifulsoup4`` for the six crawlers that import them at module scope # (c.f. the ``test`` extra's own comment below for which, and #507). #910 # narrowed ``all`` to core addons only, so this extra names all three # itself rather than leaning on ``all`` to also carry them -- ``pycrate`` @@ -302,11 +302,11 @@ test = [ # rather than failing, so the byte-for-byte regeneration check that is the # only guard on the hand-maintained IPX socket registry never runs on any CI # path: every ``unit-tests.yml`` job's install line builds on ``.[test]``, - # and ``cron-vendor.yml`` installs ``.[all]`` but never invokes pytest. + # and ``cron-vendor.yml`` installs ``.[all,vendor]`` but never invokes pytest. # # Both are needed, not just ``requests``. ``pcapkit.vendor.default`` imports # ``requests`` at module scope, and ``pcapkit.vendor.__init__`` then imports - # every crawler unconditionally -- seven of which import ``bs4`` at module + # every crawler unconditionally -- six of which import ``bs4`` at module # scope. Its ``try: import bs4`` guard suppresses only the warning, not the # ``ModuleNotFoundError`` that the crawler imports below it raise anyway. # @@ -346,9 +346,8 @@ test = [ # said nothing at all. "isort", # The second opinion on the hand-rolled YAML scanners: the ``yaml.safe_load`` - # cross-checks in ``tests/project/test_project_status.py``, - # ``test_release_gates.py``, ``test_bump_version.py`` and - # ``test_workflow_apt_timeouts.py`` skip without it. + # cross-checks under ``tests/project/``, and the tests there that parse a + # workflow with it outright, skip without it. # Test-only, as ``pcapkit`` never imports ``yaml``. Unpinned, since # ``safe_load`` is all they use. "PyYAML", diff --git a/util/bump_version.py b/util/bump_version.py index b343f186e9..cf3fe6ec9b 100644 --- a/util/bump_version.py +++ b/util/bump_version.py @@ -57,9 +57,9 @@ actually going out. Until then this is the better of the two available answers, and the ``version`` half is guarded by a test that fails when the file drifts from ``pcapkit.__version__`` -- which also covers the version changes made by hand, -which never run this script at all. Those are 40 of the 159 commits that have -moved ``__version__`` on ``main``, a quarter over the project's life and a rising -share lately: 11 of the most recent 25. +which never run this script at all. Those are 40 of the 167 commits that have +moved ``__version__`` on ``main``: a quarter over the project's life, and 11 of +the most recent 25. The rewrite is line-oriented rather than a :mod:`yaml` load-and-dump. A round trip through a YAML library would reorder keys, normalise quoting, and drop the diff --git a/util/changelog_md.py b/util/changelog_md.py index 1f52b86f22..21f5da8275 100644 --- a/util/changelog_md.py +++ b/util/changelog_md.py @@ -509,13 +509,12 @@ def convert_traced(rst: str) -> tuple[str, list[tuple[int, int]]]: # 1. setext heading -> ATX, one level per underline character: ``=`` # for the version heading, ``-`` for a module section, ``~`` for a # kind subsection underneath it. The underline is consumed outright - # on an *exact* length match against the title above it -- the - # same narrow test as before, now applied to three characters - # instead of one. reStructuredText itself only requires the - # underline to be no shorter than the title, so an over-long one - # falls straight through this check and is joined into the prose by - # rule 6 like any other unconverted construct, where the residual - # guard's mid-line pattern catches it. The heading is attributed to + # on an *exact* length match against the title above it, whichever + # of the three characters it uses. reStructuredText itself only + # requires the underline to be no shorter than the title, so an + # over-long one falls straight through this check and is joined into + # the prose by rule 6 like any other unconverted construct, where the + # residual guard's mid-line pattern catches it. The heading is attributed to # the title, not to the underline that followed it, because the # title is what a reader would look for. if index + 1 < len(lines) and line and len(lines[index + 1]) == len(line): diff --git a/util/pyshark_encap_map.py b/util/pyshark_encap_map.py index 3208f09412..8aa4041134 100644 --- a/util/pyshark_encap_map.py +++ b/util/pyshark_encap_map.py @@ -122,8 +122,8 @@ measured and committed) -- see :class:`EncapSweepError`. Ubuntu noble's packaged Wireshark, what every ``apt``-based CI runner installs, is 4.2.2: its ``editcap -T`` accepts 224 encapsulations, not 226, so this script's own -assertion trips there every time, by design (found the hard way: PR #853's -first CI run, three legs, ``AssertionError: 224 != 226``). +assertion trips there every time, by design (found the hard way: the first +CI run for #851, three legs, ``AssertionError: 224 != 226``). That is harmless to the *committed* tables at runtime -- an ``ENCAP_TYPE_TO_LINKTYPE``/``FILTER_NAME_TO_LINKTYPE`` entry a 4.2.2 install diff --git a/util/run_unittest_leg.py b/util/run_unittest_leg.py index a60fecc856..be420546e5 100644 --- a/util/run_unittest_leg.py +++ b/util/run_unittest_leg.py @@ -84,10 +84,11 @@ GitHub issue #1029 -- sharding a leg: ``directory`` may be a deeper path such as ``protocols/internet``, and ``--exclude SUBDIR`` (repeatable) drops a subdirectory, so ``protocols --exclude protocols/internet`` is "the rest". The -workflow uses that pair to split :mod:`tests.protocols` into two cells. Every -leg invoked without ``--exclude`` behaves exactly as before. The price is that -modules in different shards no longer share a process, so pollution between -them is invisible; the workflow comment records the measured pair counts. +workflow uses that pair to split :mod:`tests.protocols` into two cells. A leg +invoked without ``--exclude`` runs every unit-tier module under its directory. +The price is that modules in different shards do not share a process, so +pollution between them is invisible; the workflow comment records the measured +pair counts. What this still does not catch: a defect running the *other* direction (a root module polluting a directory module), interference between two diff --git a/util/vendor_code_changed.py b/util/vendor_code_changed.py index c70c48f2de..615a3f426c 100644 --- a/util/vendor_code_changed.py +++ b/util/vendor_code_changed.py @@ -2,9 +2,9 @@ """Whether a Vendor Update regeneration changed code, or only comments and docstrings. :file:`.github/workflows/cron-vendor.yml` runs ``pcapkit-vendor`` and isort, then -``tj-actions/verify-changed-files``. Until #1674 any changed file bumped the -version, and every bump starts a release. Of the bumps 1.5.0b5 to b12, all but -b5 and b8 changed only comments or docstrings by this script's rule: b9 a draft +``tj-actions/verify-changed-files``. Without this script any changed file would +bump the version, and every bump starts a release. Of the bumps 1.5.0b5 to b12, +all but b5 and b8 changed only comments or docstrings by this script's rule: b9 a draft becoming RFC 10049, b10 and b11 reference formatting (#1664). The owner's ruling on #1674 is that such a regeneration is committed without a bump, and only a code change cuts a beta. @@ -35,8 +35,7 @@ Paths are the arguments, or else ``$CHANGED_FILES`` split on whitespace, the separator ``verify-changed-files`` uses. Writes ``code_changed=true`` or ``code_changed=false`` to ``$GITHUB_OUTPUT``. Exits non-zero, writing nothing, -only when it has no paths to judge. The workflow then bumps, as it did before -#1674. +only when it has no paths to judge, and the workflow then bumps. """ diff --git a/util/verdict_covers_checkout.py b/util/verdict_covers_checkout.py index 05f283f068..5c759e358d 100644 --- a/util/verdict_covers_checkout.py +++ b/util/verdict_covers_checkout.py @@ -20,7 +20,7 @@ lost by that: ``HEAD``'s own ``Unit Tests`` run raises the workflow again when it completes, bot commits included -- since #401 (bb900906b, 2026-09-15) they are pushed with a deploy key, not with ``GITHUB_TOKEN``, whose events "will not create -a new workflow run" (GitHub, "Triggering a workflow from a workflow"). All 17 bot +a new workflow run" (GitHub, "Triggering a workflow from a workflow"). All 21 bot commits on ``main`` since have their own ``push`` run of ``Unit Tests``, f4f94bcad's being 38325349953; the three before #401, 5d5d8af4d, 48bc11384 and e4d0823db, have none. The second case only saves waiting for that run where it