ci: fix shellcheck findings and trim workflow comments (#1967)

.github/workflows/ci-timing.yml

@@ -1,22 +1,19 @@
 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, 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`.
-# docs/source/contributing/workflows.rst has the thresholds and why each sits
-# where it does; conventions/process.rst has what to do when one fires.
+# The periodic CI-duration review (#1538). util/ci_timing.py reads the last
+# week of runs through the API, writes a report to the job summary and an
+# artifact, and fails when a HARD threshold fires (status 1; 2 and 3 are an
+# unreadable API and a crash). GitHub emails a scheduled workflow's failures to
+# whoever last edited its cron line, so no `issues: write` is needed. The
+# thresholds are in docs/source/contributing/workflows.rst, the response to one
+# in conventions/process.rst.
 #
-# Deliberately not a `workflow_run` on Unit Tests: that would add a job per run
-# to a runner pool already measured saturated at 20 concurrent jobs.
+# Not a `workflow_run` on Unit Tests: that adds a job per run to a runner pool
+# already measured saturated.
 on:
   schedule:
     # Mondays 07:23 UTC: off the hour, where GitHub delays scheduled runs most,
-    # and clear of Saturday's crons, 02:00 to 18:00 since #1967, and Project
-    # Status at 00:37.
+    # and clear of the Saturday crons (#1967) and Project Status at 00:37.
     - cron: '23 7 * * 1'
   workflow_dispatch:
     inputs:
@@ -29,9 +26,8 @@ on:
         type: number
         default: 0
 
-# 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 made 677 (#1930).
+# GITHUB_TOKEN allows 1,000 API requests an hour per repository; a default run
+# made 677 (#1930).
 permissions:
   actions: read
   contents: read
@@ -44,20 +40,18 @@ jobs:
   report:
     name: CI timing report
     runs-on: ubuntu-latest
-    # Three nested limits, each under the next, so that a slow week ends in a
-    # smaller report rather than none (#1930). The script stops reading jobs at
-    # --budget-minutes and writes what it has. The step's cap is the backstop, and
-    # sits far enough above to let a request already in flight finish its retries.
-    # This one leaves room for the setup steps and the uploads after it. Measured
-    # for #1930, a full sample took 16.6 minutes, nearly all of it job reads, which
-    # the API answers at up to 2.4 s each and which are made one at a time.
+    # Three nested limits, so a slow week ends in a smaller report rather than
+    # none (#1930): the script stops reading jobs at --budget-minutes and writes
+    # what it has; the step's cap sits far enough above it for an in-flight
+    # request to finish its retries; this one leaves room for setup and uploads.
+    # A full sample took 16.6 minutes for #1930, nearly all of it serial job
+    # reads at up to 2.4 s each.
     timeout-minutes: 40
 
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      # #1660: `latest` from .github/python-versions.toml, read with the
-      # runner's own python3.
+      # #1660: `latest` from .github/python-versions.toml.
       - name: Read the Python versions
         id: python-versions
         run: python3 util/python_versions.py --github-output
@@ -66,8 +60,7 @@ jobs:
         with:
           python-version: ${{ steps.python-versions.outputs.latest }}
 
-      # The script fetches with requests and parses the JUnit artifacts with lxml
-      # (#1894), and needs nothing else outside the standard library.
+      # lxml parses the JUnit artifacts (#1894).
       - name: Install requests and lxml
         run: python -m pip install requests lxml
 
@@ -106,8 +99,7 @@ jobs:
             --budget-minutes 30 --out report.json --summary report.md
 
       # `always()`, not `!cancelled()`, here and below: a report written before a
-      # cap stopped the job is still worth having (#1930), and with none written
-      # there is nothing to add.
+      # cap stopped the job is still worth having (#1930).
       - name: Add the report to the job summary
         if: ${{ always() }}
         run: |

.github/workflows/codeql-analysis.yml

@@ -4,28 +4,23 @@ on:
   push:
     branches: [main]
   pull_request:
-    # The branches below must be a subset of the branches above
     branches: [main]
   schedule:
     - cron: '0 2 * * 6'
 
 # #1968: no scopes by default. `analyze` declares the ones it needs.
 permissions: {}
 
-# Only pull-request runs may be superseded -- see the note in unit-tests.yml. A
-# ref-keyed group drops a *pending* run when a newer one joins it, which for a
-# security scan means a commit reaching main with no analysis on record.
+# Only pull-request runs may be superseded (see unit-tests.yml's
+# `concurrency`): a ref-keyed group drops a *pending* run when a newer one
+# joins, which here would leave a commit on main with no analysis on record.
 concurrency:
   group: codeql-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
   cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:
-  # This workflow used to call ./.github/workflows/unit-tests.yml and gate
-  # `analyze` behind it. That re-ran the entire unit and integration matrix
-  # against a commit the Unit Tests workflow is already testing, and it bought
-  # nothing: CodeQL reads the source, so its findings do not depend on the test
-  # suite passing. Worse, it meant a failing test suppressed the security
-  # analysis for that commit. Static analysis runs on its own.
+  # Not gated on Unit Tests: CodeQL reads the source, so its findings do not
+  # depend on the tests passing, and a failing test would suppress the scan.
   analyze:
     name: Analyze
     runs-on: ubuntu-latest
@@ -38,28 +33,11 @@ jobs:
     - name: Checkout repository
       uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-    # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
       uses: github/codeql-action/init@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
-      # Override language selection by uncommenting this and choosing your languages
-      # with:
-      #   languages: go, javascript, csharp, python, cpp, java
 
-    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
-    # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
       uses: github/codeql-action/autobuild@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
 
-    # ℹ️ Command-line programs to run using the OS shell.
-    # 📚 https://git.io/JvXDl
-
-    # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
-    #    and modify them (or add more) to build your code if your project
-    #    uses a compiled language
-
-    #- run: |
-    #   make bootstrap
-    #   make release
-
     - name: Perform CodeQL Analysis
       uses: github/codeql-action/analyze@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0

.github/workflows/coverage-comment.yml

@@ -1,12 +1,10 @@
 name: Coverage Comment
 
-# Posts the coverage the `test` job's `latest` leg measured in
-# unit-tests.yml as a pull-request comment. It runs no tests. The comment cannot
-# be posted from unit-tests.yml itself: that file is also a reusable workflow,
-# and a called workflow can only narrow the token its caller passes, never widen
-# it. Every caller grants `contents: read`, so asking for
-# `pull-requests: write` there would break every one of them, the release gate
-# included.
+# Posts the coverage the `test` job's `latest` leg measured in unit-tests.yml
+# as a pull-request comment. Not from unit-tests.yml itself: that file is also a
+# reusable workflow whose callers grant `contents: read`, and a called workflow
+# can only narrow its caller's token, so `pull-requests: write` there would
+# break every caller, the release gate included.
 #
 # `workflow_run` runs this file as it is on the default branch, with a token of
 # its own, so fork pull requests get a comment too. The price is that the