ci: keep workflow and release-doc comments in step with the ruleset and pins (#2231)

.github/workflows/create-release.yml

@@ -442,7 +442,7 @@ jobs:
           # release upload``, which never calls Update a release; cron-conda.yml's
           # upload does, naming the default branch: see releasing.rst.
           target_commitish: ${{ github.event_name == 'workflow_run' && github.sha || '' }}
-          # "A non-empty explicit token overrides GITHUB_TOKEN" (3.0.2's
+          # "A non-empty explicit token overrides GITHUB_TOKEN" (the action's
           # ``action.yml``), so no ``env:`` names one.
           token: ${{ steps.app_token.outputs.token || secrets.GITHUB_TOKEN }}
 
@@ -673,10 +673,10 @@ jobs:
           attestations: false
 
       # #1634: ``gh release upload``, not ``action-gh-release``, which calls
-      # Update a release before every upload (3.0.2's ``src/github.ts``), where
-      # GitHub re-checks the release's target against the workflow-file rule: a
-      # workflow change reaching ``main`` after ``github`` ran would fail this
-      # after PyPI had published. #1640: a file already ``uploaded`` is left
+      # Update a release before every upload (``release`` in its
+      # ``src/github.ts``), where GitHub re-checks the release's target against
+      # the workflow-file rule: a workflow change reaching ``main`` after
+      # ``github`` ran would fail this after PyPI had published. #1640: a file already ``uploaded`` is left
       # alone, as a rebuild is not byte-identical; after a 502 an asset "may
       # leave an empty asset with a state of starter", which ``--clobber``
       # replaces. A missing release fails ("release not found") where the action

.github/workflows/cron-conda.yml

@@ -736,7 +736,7 @@ jobs:
       # main's tip and fail Create Release's tag check. It also retargets a
       # draft at ``commit`` (``updateDraftOrCreateRelease`` and
       # ``updateRelease``), though Create Release's ``workflow_run`` run resets
-      # a draft's target to its sha (softprops/action-gh-release v3.0.2,
+      # a draft's target to its sha (softprops/action-gh-release v3.0.3,
       # ``release`` and ``findTagFromReleases`` in src/github.ts); skipping a
       # draft is a precaution. Only the GitHub upload is skipped; the build is
       # on anaconda.org regardless.

.github/workflows/cron-vendor.yml

@@ -115,10 +115,10 @@ jobs:
           python -m pip install -U pip setuptools wheel packaging
           python -m pip install -U isort
 
-          # `vendor` for `requests` and `beautifulsoup4`, which `all` lacks
-          # since #910: `pcapkit-vendor` with no target runs every crawler, and
-          # some import them at module scope (#507). See the `vendor` extra's
-          # comment in pyproject.toml.
+          # `vendor` for `requests` and `beautifulsoup4`, which `all` does not
+          # carry, as it holds core addons only (#910): `pcapkit-vendor` with no
+          # target runs every crawler, and some import them at module scope
+          # (#507). See the `vendor` extra's comment in pyproject.toml.
           python -m pip install -e '.[all,vendor]'
 
       - name: Update Vendor
@@ -271,9 +271,10 @@ jobs:
         run: |
           git config --local user.email "github-actions[bot]@users.noreply.github.com"
           git config --local user.name "github-actions[bot]"
-          # #1685: `-a` skips untracked files, so a new module was bumped for but
-          # never committed, and every later crawl bumped again. Quoted, so git
-          # matches at any depth; `.py` only, so a leftover backup stays out.
+          # #1685: `-a` skips untracked files, so a new module is staged here;
+          # left out, it would stay uncommitted and every later crawl would bump
+          # for it again. Quoted, so git matches at any depth; `.py` only, so a
+          # leftover backup stays out.
           git add -A -- 'pcapkit/const/*.py'
           git commit -am"Bumped version to $(python -c 'import pcapkit; print(pcapkit.__version__)')
 

.github/workflows/unit-tests.yml

@@ -1406,12 +1406,13 @@ jobs:
         run: python util/cap_file_size.py python -m pytest -q -n auto --dist load
 
   # Ruleset 23497679's required_status_checks requires these contexts: this
-  # job's `Required checks passed`, and a `Compat Python` one per supported version,
-  # from the `compatibility` job in `.github/workflows/python-compatibility.yml`.
+  # job's `Required checks passed`, a `Compat Python` one per supported version,
+  # from the `compatibility` job in `.github/workflows/python-compatibility.yml`,
+  # and `Lint`, from the `lint` job in `.github/workflows/lint.yml`.
   # Rulesets match check names literally and support no wildcard, so this job
   # aggregates the gating jobs its `needs:` lists rather than the ruleset naming
-  # each matrix cell. The `Compat` legs are required on their own because a job
-  # cannot `needs:` a job in another workflow file.
+  # each matrix cell. The `Compat` legs and `Lint` are required on their own
+  # because a job cannot `needs:` a job in another workflow file.
   #
   # `if: ${{ always() && inputs.gate-only != true }}` and the explicit
   # per-job check below are both required, not decorative:

docs/source/contributing/releasing.rst

@@ -173,7 +173,7 @@ the default branch, and ``tag`` pulls ``main`` before tagging.
   build, by Conda Update's ``publish`` dispatch (see `Recovery`_).
 * ``pypi`` and ``conda`` attach their files with ``gh release upload``, in
   their "Upload package to GitHub Release" steps, not ``action-gh-release``,
-  which calls Update a release before every upload (3.0.2's ``release()`` in
+  which calls Update a release before every upload (3.0.3's ``release()`` in
   ``src/github.ts``, on a release that exists). A file
   the release already has is left alone
   (:issue:`1640`): the action
@@ -253,7 +253,7 @@ tag the pending version at ``main``'s tip and fail Create Release's tag check.
 The action would also retarget a draft at ``commit``
 (``Action.updateDraftOrCreateRelease()`` and ``Action.updateRelease()``), which ``omitDraftDuringUpdate`` keeps a
 draft, but Create Release's ``workflow_run`` run finds the draft and resets
-its target to the run's sha (``action-gh-release`` 3.0.2's ``release()`` and
+its target to the run's sha (``action-gh-release`` 3.0.3's ``release()`` and
 ``findTagFromReleases()``), so skipping a draft is a precaution
 against retargeting a release Create Release owns.
 Either way the build goes to anaconda.org only, with a ``::notice``. The
@@ -319,7 +319,7 @@ final release, first delete any draft ``v<version>`` the refused run left:
 ``action-gh-release`` creates a non-prerelease as a draft and publishes it
 with Update a release in the same step (``createRelease()`` in
 ``src/github.ts``), and the next run would reuse that draft and its target
-(``:631-647`` there). Then re-run
+(``release()`` there). Then re-run
 the job; that a re-run reads variables and secrets set since is unmeasured.
 
 Per-Job Evidence, Not a Shared Proxy

tests/project/test_release_tags_the_run_sha_1634.py

@@ -318,7 +318,7 @@ def releases(self) -> 'list[tuple[str, dict[str, Any]]]':
     def test_only_github_runs_the_release_action(self) -> None:
         """``pypi`` and ``conda`` used it to upload, which re-checked the target.
 
-        ``action-gh-release`` 3.0.2 calls Update a release on an existing
+        ``action-gh-release`` 3.0.3 calls Update a release on an existing
         release before uploading anything (``release`` in ``src/github.ts``), passing
         the release's own ``target_commitish`` when the input is unset, and
         GitHub's REST docs apply the workflow-file rule there to "the new value
@@ -401,7 +401,7 @@ def test_it_is_minted_straight_before_create_release(self) -> None:
         self.assertEqual(self.index('github', MINT_STEP) + 1, self.steps['github'].index(self.create_release()))
 
     def test_only_create_release_spends_it(self) -> None:
-        """The ``token:`` input, with no ``env:`` beside it: 3.0.2's ``parseToken``
+        """The ``token:`` input, with no ``env:`` beside it: 3.0.3's ``parseToken``
         prefers a non-empty ``INPUT_TOKEN`` and falls back to ``GITHUB_TOKEN``
         (``src/util.ts``), so an ``env:`` token would only ever be a
         second credential handed to the action."""
@@ -1642,7 +1642,7 @@ def test_a_new_release_gets_every_file_in_order(self) -> None:
 
     def test_a_pattern_matching_nothing_fails(self) -> None:
         """A change from the action, which only warned: ``fail_on_unmatched_files``
-        is unset here, so 3.0.2's ``run`` in ``src/run.ts`` logs "🤔 Pattern '…' does
+        is unset here, so 3.0.3's ``run`` in ``src/run.ts`` logs "🤔 Pattern '…' does
         not match any files." and carries on."""
         self.published()
         result = self.upload('pypi')
@@ -1652,7 +1652,7 @@ def test_a_pattern_matching_nothing_fails(self) -> None:
 
     def test_a_missing_release_fails_before_any_upload(self) -> None:
         """A change from the action, which made one: with no release for the tag,
-        3.0.2 calls ``createRelease`` (from ``release`` in ``src/github.ts``) with
+        3.0.3 calls ``createRelease`` (from ``release`` in ``src/github.ts``) with
         no notes and ``target_commitish`` unset (``parseConfig`` in ``src/util.ts``), which
         Create a release defaults to "the repository's default branch". Making
         the release is ``github``'s job, at the run's commit."""
@@ -1706,7 +1706,7 @@ class TestCondaUpdateNeverMakesTheRelease(CondaDistMixin, unittest.TestCase):
     (``omitDraftDuringUpdate``, through ``CoreInputs.updatedDraft`` in
     ``src/Inputs.ts``) but is retargeted at ``commit``; Create Release's
     ``workflow_run`` run finds the draft and resets its target to the run's sha
-    (``action-gh-release`` 3.0.2's ``release`` and ``findTagFromReleases`` in
+    (``action-gh-release`` 3.0.3's ``release`` and ``findTagFromReleases`` in
     ``src/github.ts``), so skipping a draft is a precaution against retargeting
     a release Create Release owns. On an existing release it calls Update a
     release with ``target_commitish: commit`` (``Action.updateRelease`` in

tests/project/test_unit_tests_queue.py

@@ -634,11 +634,7 @@ def test_the_scan_is_not_blind(self) -> None:
 #: A document that names one of :data:`BY_NAME` may still cite another file bare,
 #: as ``:N``; each such citation is listed here with the file it does cite, and
 #: any other bare citation there reads as a line of the named workflow.
-BARE_ELSEWHERE: 'dict[str, dict[str, str]]' = {
-    'docs/source/contributing/releasing.rst': {
-        '631-647': "softprops/action-gh-release 3.0.2's src/github.ts",
-    },
-}
+BARE_ELSEWHERE: 'dict[str, dict[str, str]]' = {}
 
 #: A line-number citation: ``N``, ``N-M``, or several joined by commas.
 SPANS = r'(\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*)'