docs(repo): seventh whole-repo pass over util, examples, workflows and root files (#1103)

Full read of util/, examples/, workflow comments and root config.

- util: changelog_md sdist scope, pyshark_encap_map Unassigned handling and
  lxml markers, pytest_shards interpreter, python_versions KTLO outputs,
  release_tags/vendor_test_gate/update_python_versions/superseded claims.
- examples: options.py HIP/SMF_DPD/PCAP-NG notes, pcapng.py logging,
  dispatch.py, legacy.py, engine lists.
- workflows: unittest-ordering cap comments, lint schedule, deploy-pages
  leftover comment, milestone duplicate-closed, status_for cited by name.
- root: Makefile captures, pyproject test extra, .gitignore wording.
- Change-relative wording and counts restated throughout.

Author: JarryShaw

.github/workflows/coverage-comment.yml

@@ -100,7 +100,7 @@ jobs:
           if tests not in ('success', 'failure', 'cancelled', 'skipped'):
               sys.exit(f'invalid test outcome in artifact: {tests!r}')
           total = number(data['total'])
-          # The leg's version, from the artifact; one written before #1660 has none.
+          # The leg's version, from the artifact; one without it reads as the coverage leg.
           python = data.get('python')
           if python is not None and not (isinstance(python, str) and re.fullmatch(r'3\.\d+', python)):
               sys.exit(f'invalid Python version in artifact: {python!r}')

.github/workflows/create-release.yml

@@ -752,8 +752,7 @@ jobs:
           - macos-latest
           - macos-26-intel
           - ubuntu-latest
-          # #2060: win-64, once Conda Update's leg had built and smoke-tested it
-          # green. Its `run:` steps name `bash`, as Windows runs `pwsh`.
+          # #2060: win-64. Its `run:` steps name `bash`, as Windows runs `pwsh`.
           - windows-latest
         # #1633, #1660: the supported tier only. No KTLO 3.10 leg: the list
         # util/conda_vendor.py derives omits typing-extensions, which

.github/workflows/cron-conda.yml

@@ -551,7 +551,7 @@ jobs:
           - macos-26-intel
           - ubuntu-latest
           # #2060: win-64, uploaded with the anaconda-client CLI as the Intel
-          # leg is, once its runs had built and smoke-tested it green.
+          # leg is.
           - windows-latest
         # #1633: the supported tier, from .github/python-versions.toml through
         # `conda-update` (#1660); create-release.yml's ``conda`` job says why

.github/workflows/cron-vendor.yml

@@ -180,10 +180,10 @@ jobs:
           find pcapkit/const -mindepth 2 -name '*.py' -exec isort -l100 -ppcapkit {} +
 
       # #1853: both gates in `head` judge the commit from before the crawl, so
-      # 1.5.0b13 was committed with a test failing on it. The owner's ruling:
-      # test it here under #872's rule -- a module the tests fail with goes
-      # back to HEAD's copy, the rest are committed. util/vendor_test_gate.py's
-      # docstring gives the rule.
+      # they pass a crawl the tests fail on, as they did 1.5.0b13's. The
+      # owner's ruling: test it here under #872's rule -- a module the tests
+      # fail with goes back to HEAD's copy, the rest are committed.
+      # util/vendor_test_gate.py's docstring gives the rule.
       #
       # `continue-on-error`, so the tests never fail the job; if the step fails
       # or times out, the next one discards every regenerated module. `.[test]`

.github/workflows/deploy-pages.yml

@@ -77,7 +77,7 @@ jobs:
         github.event.workflow_run.head_branch == 'main' &&
         needs.head.outputs.verified == 'true'
       ))
-    concurrency: ci-${{ github.event_name == 'workflow_dispatch' && github.run_id || github.ref }} # Recommended if you intend to make multiple deployments in quick succession.
+    concurrency: ci-${{ github.event_name == 'workflow_dispatch' && github.run_id || github.ref }}
     runs-on: macos-latest
     steps:
       - name: Checkout 🛎️

.github/workflows/lint.yml

@@ -30,7 +30,7 @@ on:
   pull_request:
     branches: [main]
   schedule:
-    # Saturdays, an hour clear of the other Saturday jobs.
+    # Saturdays, at an hour no other Saturday job uses.
     - cron: '0 6 * * 6'
   workflow_dispatch:
 

.github/workflows/milestone.yml

@@ -7,15 +7,15 @@ name: Milestone
 # "Milestone" in docs/source/contributing/workflows.rst: an open item, a merged
 # pull request or an issue closed as completed gets the open milestone named
 # after the checked-out `pcapkit.__version__`, unless it already holds another;
-# an unmerged pull request or an issue closed as not planned loses whichever
-# milestone it holds. A missing milestone is a warning, never created.
+# an unmerged pull request or an issue closed as not planned or as a duplicate
+# loses whichever milestone it holds. A missing milestone is a warning, never created.
 #
 # SECURITY. `pull_request_target` gives this run a write token on events a
 # stranger can cause, so it must never execute anything the pull request
 # supplies. The job below:
 #
 #   * checks out `github.sha`, which under `pull_request_target` is the tip of
-#     the *base* branch, never the PR head, and only the three files it reads,
+#     the *base* branch, never the PR head, and only the files it reads,
 #     without persisting the token;
 #   * reads `__version__` from pcapkit/__init__.py as text, importing nothing;
 #   * takes nothing from the event payload but the item number, passed through

.github/workflows/project-status.yml

@@ -2,7 +2,7 @@ name: Project Status
 
 # Keeps the project board's Status field (users/JarryShaw/projects/2) in line with
 # each item's state labels, which no built-in board workflow observes. The mapping
-# is util/project_status.py:status_for; it and the PROJECT_TOKEN setup are
+# is `status_for` in util/project_status.py; it and the PROJECT_TOKEN setup are
 # documented under "Milestones and the Project Board" in
 # docs/source/contributing/conventions/process.rst.
 #

.github/workflows/unit-tests.yml

@@ -123,7 +123,7 @@ jobs:
           cache: pip
 
       # DPKT (#729), crypto and NGAP (#738) are here so the unit-tier tests
-      # gated on them run instead of skipping; all three install cleanly. On
+      # gated on them run instead of skipping; each installs cleanly. On
       # PyPy 8.0 PyPI has no Linux wheel of cryptography, so pip builds it with
       # the image's Rust and libssl-dev (#1958). `cli` (emoji) is not here: its
       # only gated tests are in tests/integration, which this job ignores.
@@ -1166,8 +1166,8 @@ jobs:
     runs-on: ubuntu-latest
     # 45, as `test`'s: this is the only test job with no xdist, so a cell
     # carries its whole serial cost, and a contended run once passed 20
-    # minutes. The slowest cell, with #1029's split, is 8.2m; even #1029's slowdown
-    # window, at least 1.6x, leaves it far inside the cap.
+    # minutes. Each cell is held well inside it by its run step's own cap,
+    # which ci-timing.yml's weekly report watches (#2254).
     timeout-minutes: 45
     strategy:
       fail-fast: false
@@ -1224,8 +1224,9 @@ jobs:
           python -c "import os; print('cpu_count', os.cpu_count())"
 
       # `--verbose` names every test as it runs, so a hung cell shows where it
-      # was. The step cap is about twice the slowest cell's measured maximum,
-      # under the job's, so a hang reports as this step timing out.
+      # was. The step cap sits under the job's, so a hang reports as this step
+      # timing out. util/ci_timing.py flags a cell whose p90 reaches half of
+      # it, and such a cell is split, as `project` is (#2254).
       - name: Run tests/${{ matrix.leg }} and the root-level modules under plain unittest
         timeout-minutes: 20
         run: python util/cap_file_size.py python util/run_unittest_leg.py ${{ matrix.leg }} ${{ matrix.exclude }} ${{ matrix.shard }} --verbose

.gitignore

@@ -6,20 +6,19 @@ pcapkit-temp.html
 # generated captures at examples/sample/, and nothing should track them.
 examples/sample/
 examples/captures/*
-# Only the two genuine *inputs* are tracked. Everything else in this directory is
-# build output: the captures `examples/generators/make_samples.py` writes, and the
-# reference reports `examples/legacy_smoke/` renders out of these two inputs --
-# out.json, out.plist, out.txt and pcapng.txt, via `make fixtures` there.
+# Only the genuine *inputs*, re-included below, are tracked. Everything else in
+# this directory is build output: the captures `examples/generators/make_samples.py`
+# writes, and the reference reports `examples/legacy_smoke/` renders out of those
+# inputs -- out.json, out.plist, out.txt and pcapng.txt, via `make fixtures` there.
 #
-# Those four used to be tracked, and the reason they no longer are is that a
-# tracked report goes stale silently. Nothing reads one back, so nothing notices
-# when a parser change alters how a frame renders: #685 was exactly that, with
-# pcapng.txt still recording `packet -> NIL` for four blocks long after #683 gave
-# PCAP-NG packet blocks their captured octets back. Regenerating them on every such
-# change is work with no reader, and the tier guard in `tests/_tiers.py` asks git
-# which captures are tracked rather than hardcoding a list, so dropping them here
-# is the whole change -- see `examples/legacy_smoke/README.md` for how to rebuild
-# them locally.
+# The reports are not tracked because a tracked report goes stale silently.
+# Nothing reads one back, so nothing notices when a parser change alters how a
+# frame renders: #685 was exactly that, with pcapng.txt still recording
+# `packet -> NIL` for four blocks long after #683 gave PCAP-NG packet blocks their
+# captured octets back. Regenerating them on every such change is work with no
+# reader, and the tier guard in `tests/_tiers.py` asks git which captures are
+# tracked rather than hardcoding a list, so ignoring them here is all it takes --
+# see `examples/legacy_smoke/README.md` for how to rebuild them locally.
 !examples/captures/in.pcap
 !examples/captures/dhcp.pcapng