ci: cite pinned third-party code by name, not line (#1103)

.github/workflows/cron-conda.yml

@@ -730,13 +730,16 @@ jobs:
 
       # #1634: the upload below never makes the release. ncipollo/release-action
       # v1.21.0 creates a missing one, and its tag, at ``commit``
-      # (src/Action.ts:72-92), so a bump made while Create Release waits on
-      # approval would tag the pending version at main's tip and fail Create
-      # Release's tag check. It also retargets a draft at ``commit``
-      # (:85-92,107-120), though Create Release's ``workflow_run`` run resets a
-      # draft's target to its sha (softprops/action-gh-release v3.0.2,
-      # src/github.ts:636-646,832-866); skipping a draft is a precaution. Only
-      # the GitHub upload is skipped; the build is on anaconda.org regardless.
+      # (``Action.checkForMissingReleaseError`` and
+      # ``Action.updateDraftOrCreateRelease`` in src/Action.ts), so a bump made
+      # while Create Release waits on approval would tag the pending version at
+      # 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,
+      # ``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.
       - name: Check the GitHub release exists
         id: release
         if: ${{ needs.mode.outputs.publishes == 'true' && matrix.os == 'ubuntu-latest' }}
@@ -765,17 +768,22 @@ jobs:
           echo "published=false" >> "$GITHUB_OUTPUT"
 
       # ``commit`` is sent to Update a release as ``target_commitish``
-      # (src/Action.ts:107-120, src/Releases.ts:150-174), and
+      # (``Action.updateRelease`` in src/Action.ts, ``GithubReleases.update`` in
+      # src/Releases.ts), and
       # ``github.ref_name`` is the default branch on every run that publishes, so
       # GitHub's workflow-file rule checks main, not the commit Create Release
       # made the release at. The tag stays: the target is "Unused if the Git
       # tag already exists" (REST docs, Update a release).
       #
       # #1657: that update also sends ``name``, ``body``, ``prerelease`` and
-      # ``draft``, which unset inputs make the tag, "" and false
-      # (src/Inputs.ts:70-92,128-135,210-240), so each bump wiped the release's
-      # name and notes. Each ``omit*DuringUpdate`` leaves its field undefined
-      # (:210-252), and Octokit drops it (dist/index.js:38369-38388).
+      # ``draft``, which unset inputs make the tag, "" and false (the
+      # ``CoreInputs`` getters ``name``, ``body``, ``createdPrerelease`` and
+      # ``createdDraft`` in src/Inputs.ts, read through its ``updated*``
+      # getters), so each bump wiped the release's name and notes. Each
+      # ``omit*DuringUpdate`` leaves its field undefined (the same ``updated*``
+      # getters), and Octokit drops it (@octokit/endpoint's
+      # ``removeUndefinedProperties``, called from its ``merge``, bundled in
+      # dist/index.js).
       - name: Upload package to GitHub Release
         if: ${{ needs.mode.outputs.publishes == 'true' && matrix.os == 'ubuntu-latest' && steps.release.outputs.published == 'true' }}
         uses: ncipollo/release-action@339a81892b84b4eeb0f6e744e4574d79d0d9b8dd # v1.21.0

.github/workflows/experimental.yml

@@ -148,7 +148,8 @@ jobs:
   # job-level guard covers that. So every step that can run long
   # carries a cap of its own under the job's: a step past its cap fails rather
   # than cancels, and `continue-on-error` then applies as to any failure
-  # (actions/runner src/Runner.Worker/StepsRunner.cs:322-353, at 5f0b3ddcc).
+  # (actions/runner `StepsRunner.RunStepAsync` in
+  # src/Runner.Worker/StepsRunner.cs, at 5f0b3ddcc).
   # tests/project/test_ktlo_legs_stay_green_1672.py pins the caps and the
   # minutes they leave the rest.
   #
@@ -254,12 +255,14 @@ jobs:
       # #1740: GraalPy's leg can lose its runner mid-tests ("The runner has
       # received a shutdown signal"), and then the runner evaluates no later
       # step's condition, `always()` included (actions/runner
-      # src/Runner.Worker/StepsRunner.cs:205-208, at 796cc18ff). So this samples
-      # the runner every 30 s into resource-monitor.log, and `Run unit tests`
-      # follows the file into its own log, the one record a lost runner leaves.
-      # The sampler holds none of this step's output: the runner kills a step's
-      # process tree 5 s after its shell exits while a child still holds it
-      # (src/Runner.Sdk/ProcessInvoker.cs:485-505, same commit). `set +eo
+      # `StepsRunner.RunAsync` in src/Runner.Worker/StepsRunner.cs, at
+      # 796cc18ff). So this samples the runner every 30 s into
+      # resource-monitor.log, and `Run unit tests` follows the file into its own
+      # log, the one record a lost runner leaves. The sampler holds none of this
+      # step's output: the runner kills a step's process tree 5 s after its
+      # shell exits while a child still holds it
+      # (`ProcessInvoker.ProcessExitedHandler` in
+      # src/Runner.Sdk/ProcessInvoker.cs, same commit). `set +eo
       # pipefail`: `shell: bash` sets both, and `ps | head` can end `ps` with
       # SIGPIPE. Started here, the sampler is outside the tests' memory scope,
       # so an OOM kill there leaves it running.
@@ -317,7 +320,7 @@ jobs:
       #   Java heap alone, not thread stacks or JIT code (graalvm.org, Native
       #   Image, Memory Management), and a heap the GC cannot free raises
       #   OutOfMemoryError, which GraalPy turns into MemoryError (graalpython
-      #   runtime/exception/ExceptionUtils.java:313-316, at graal-25.4.4).
+      #   `ExceptionUtils.wrapJavaExceptionIfApplicable`, at graal-25.4.4).
       # - #1753: a worker's live heap grows with its tests until no heap lasts
       #   the tier, and a MemoryError in pytest's own failure report ends the
       #   session. `-XX:+ExitOnOutOfMemoryError` ends that worker instead, and
@@ -341,13 +344,14 @@ jobs:
       # - `prlimit --fsize`: no file over 2 GiB.
       # - A transient scope, 12G and no swap, at a fifth of the runner's CPU
       #   weight, where `sudo -n` can start one; otherwise uncapped. A scope's
-      #   command inherits the caller's environment (systemd-run(1), systemd
-      #   v255 man/systemd-run.xml:70-71), but sudo resets PATH and drops
-      #   `LD_*` even under --preserve-env (sudo plugins/sudoers/env.c:133-141,
-      #   at 43defa130), where setup-python puts its lib/
-      #   (src/find-python.ts:163-170, at ff73b2463), so `env` sets those
-      #   again, and the heap too. systemd-run drops to the runner's uid and
-      #   gid itself (src/run/run.c:1645-1683, v255). The probe is `scoped`
+      #   command inherits the caller's environment (systemd-run(1),
+      #   Description, systemd v255), but sudo resets PATH and drops `LD_*`
+      #   even under --preserve-env (sudo `initial_badenv_table` in
+      #   plugins/sudoers/env.c, at 43defa130), where setup-python puts its
+      #   lib/ (`useCpythonVersion` in src/find-python.ts, at ff73b2463), so
+      #   `env` sets those again, and the heap too. systemd-run drops to the
+      #   runner's uid and gid itself (`start_transient_scope` in
+      #   src/run/run.c, v255). The probe is `scoped`
       #   itself, every flag included, under a throwaway unit and running
       #   `true`, and either way the tests run the one argv, in the scope or not.
       # `tests-status` holds, for `Containment summary`, the exit status, the
@@ -358,7 +362,7 @@ jobs:
       # an exception group's `|`: a mention is not one (#1962), and nor is
       # Java's `OutOfMemoryError`. A worker down is xdist's `[gwN] node down:`
       # line, since under `-q` it prints no `replacing crashed worker`
-      # (xdist/dsession.py:78-80, at v3.8.0).
+      # (`DSession.report_line` in xdist/dsession.py, at v3.8.0).
       #
       # #1938: util/superseded.py's `watch` runs the whole command in a session
       # of its own, outside the scope, and asks `current`'s question every

.github/workflows/python-compatibility.yml

@@ -91,8 +91,8 @@ jobs:
       # with sources that do not compile -- is legible from the run summary; a
       # warning on a KTLO leg (#1672). Each title escapes `,` as
       # `%2C`: the runner splits a command's properties on `,`, so the KTLO
-      # title would stop at "(KTLO" (actions/runner
-      # src/Runner.Common/ActionCommand.cs:100, at 5f0b3ddcc).
+      # title would stop at "(KTLO" (actions/runner `ActionCommand.TryParseV2`
+      # in src/Runner.Common/ActionCommand.cs, at 5f0b3ddcc).
       - name: Verify package
         id: verify
         if: ${{ steps.install.outcome == 'success' }}

MANIFEST.in

@@ -28,13 +28,15 @@ prune typings
 #
 # What actually ships them, on setuptools 84.0.0:
 #
-# * ``setuptools/command/sdist.py:59-60`` sets ``READMES`` from
-#   ``README_EXTENSIONS = ['', '.rst', '.txt', '.md']``, and
-#   ``setuptools/_distutils/command/sdist.py:277-296`` appends the first of those
+# * setuptools' ``sdist`` command (``setuptools/command/sdist.py``) sets
+#   ``sdist.READMES`` from ``README_EXTENSIONS = ['', '.rst', '.txt', '.md']``,
+#   and the distutils base's ``sdist._add_defaults_standards``
+#   (``setuptools/_distutils/command/sdist.py``) appends the first of those
 #   that exists to the file list unconditionally, before ``MANIFEST.in`` is read.
 #   The ``.md`` entry is setuptools' own addition over the distutils default, so
 #   the README becoming Markdown is exactly what this line stopped mattering for.
-# * ``setuptools/dist.py:460`` supplies the default ``license_files`` glob
+# * ``Distribution._finalize_license_files`` (``setuptools/dist.py``) supplies
+#   the default ``license_files`` glob
 #   ``['LICEN[CS]E*', 'COPYING*', 'NOTICE*', 'AUTHORS*']``, used because
 #   ``pyproject.toml`` declares no ``license-files`` of its own. That is what emits
 #   ``adding license file 'LICENSE'`` in the build log, twice, in a build with this

pyproject.toml

@@ -288,8 +288,9 @@ docs = [
 test = [
     "pytest>=8",
     # >=3.6.1, not >=3: the `shouldfail` forwarding tests/conftest.py's xdist fix
-    # depends on (xdist/remote.py:146-147) lands in 3.6.0, which PyPI has yanked,
-    # so 3.6.1 is the actual floor. Below it the fix silently reverts and
+    # depends on (`WorkerInteractor.pytest_sessionfinish` in xdist/remote.py)
+    # lands in 3.6.0, which PyPI has yanked, so 3.6.1 is the actual floor.
+    # Below it the fix silently reverts and
     # test_xdist_run_reports_the_diagnostic_and_fails goes red rather than
     # skipped, since `importlib.util.find_spec('xdist')` still succeeds.
     "pytest-xdist>=3.6.1",