Write configs' docs, comments and names in one voice

.distignore

@@ -1,5 +1,4 @@
 # Baseline wp dist-archive exclusions for WordPress projects.
-# Copy this file to each consumer project root and extend it there.
 
 .git
 .github
@@ -38,8 +37,7 @@ scoper.inc.php
 .wp-env*
 .wordpress-org
 
-# Secret material — never ship, even when a consumer forgets to list it.
-# .pem is root-anchored (leading /) so certs bundled under vendor/ (e.g. CA bundles) still ship.
+# Secret material, with .pem anchored to the root so certificates bundled under vendor/ still ship.
 .env*
 /*.pem
 *.key

.github/PULL_REQUEST_TEMPLATE.md

@@ -14,7 +14,7 @@
 ## Checklist
 
 - [ ] Tests added or updated (PHPUnit suites under `tests/Unit/`)
-- [ ] `composer test` passes locally
+- [ ] The checks in CONTRIBUTING.md pass locally
 - [ ] If this changes a reusable workflow's inputs/outputs, `docs/workflows.md` is updated to reflect the new contract
 - [ ] If this changes a ruleset, downstream consumer behavior is considered (this repo ships to `dev-trunk` consumers immediately)
 

.github/actionlint.yml

@@ -1,4 +1,4 @@
-# actionlint does not know the job context's workflow_repository and workflow_sha yet, which GitHub documents for a reusable workflow's own commit.
+# The job context's workflow_repository and workflow_sha, which GitHub documents for a reusable workflow's own commit, are not yet known to actionlint.
 paths:
   .github/workflows/reusable-block-json-check.yml:
     ignore:

.github/workflows/quality.yml

@@ -17,21 +17,21 @@ permissions: {}
 
 jobs:
   lint-php:
-    name: PHP Lint
+    name: Lint PHP
     permissions:
       contents: read
     uses: ./.github/workflows/reusable-php-lint.yml
     with:
       scripts: '["lint:php:phpcs", "lint:php:phpcs:tests", "lint:php:phpstan"]'
 
   php-syntax:
-    name: PHP Syntax
+    name: Check PHP syntax
     permissions:
       contents: read
     uses: ./.github/workflows/reusable-php-syntax-check.yml
 
   php-syntax-legacy:
-    name: PHP 7.4 syntax
+    name: Check PHP 7.4 syntax
     # The fixture stands in for a consumer's by-path files, which must still parse on PHP 7.4.
     permissions:
       contents: read
@@ -41,9 +41,8 @@ jobs:
       paths: '["tests/Fixtures/build-fixture"]'
 
   phpcs-smoke:
-    name: PHPCS dist-file smoke
-    # Self-lint runs the shared profiles only through the root rulesets, which strip the WP-runtime
-    # sniffs consumers get — this job scans a plugin-shaped fixture with the raw production profile.
+    name: Smoke-test the PHPCS production profile
+    # Self-lint reaches the shared profiles only through the root rulesets, which drop the WordPress runtime sniffs consumers get, so this job scans a plugin-shaped fixture with the production profile itself.
     runs-on: ubuntu-latest
     timeout-minutes: 30
     permissions:
@@ -53,7 +52,7 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Setup PHP
+      - name: Set up PHP
         uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0
         with:
           php-version: '8.5'
@@ -65,12 +64,11 @@ jobs:
         with:
           composer-options: '--prefer-dist --ignore-platform-req=php+'
 
-      # phpcs -e loads the ruleset and lists its sniffs without scanning any file — the cheapest
-      # possible proof that the XML parses and every <rule ref> still resolves.
+      # Explaining the profile loads it and lists its sniffs without scanning a file, the cheapest proof that the XML parses and every rule reference still resolves.
       - name: Explain php/quality-assurance/phpcs.dist.xml
         run: vendor/bin/phpcs -e --standard=php/quality-assurance/phpcs.dist.xml
 
-      - name: Scan fixture with php/quality-assurance/phpcs.dist.xml
+      - name: Scan the fixture with php/quality-assurance/phpcs.dist.xml
         shell: bash
         run: |
           # The production profile skips */tests/*, so a temp copy is scanned outside that path.
@@ -88,13 +86,13 @@ jobs:
       scripts: '["lint:scripts", "lint:config"]'
 
   supply-chain:
-    name: Supply-chain audit
+    name: Audit the supply chain
     permissions:
       contents: read
     uses: ./.github/workflows/reusable-supply-chain-audit.yml
 
   supply-chain-release-tools:
-    name: Supply-chain audit (release tools)
+    name: Audit the release tools
     permissions:
       contents: read
     uses: ./.github/workflows/reusable-supply-chain-audit.yml
@@ -103,7 +101,7 @@ jobs:
       npm-audit: false
 
   supply-chain-block-json-tools:
-    name: Supply-chain audit (block.json tools)
+    name: Audit the block.json tools
     permissions:
       contents: read
     uses: ./.github/workflows/reusable-supply-chain-audit.yml
@@ -112,16 +110,16 @@ jobs:
       composer-audit: false
 
   block-json:
-    name: block.json schema check
-    # Dogfoods reusable-block-json-check against a throwaway fixture; this tooling repo ships no real blocks.
+    name: Check block.json files
+    # This repository ships no blocks, so the check runs against a fixture.
     permissions:
       contents: read
     uses: ./.github/workflows/reusable-block-json-check.yml
     with:
       project-path: tests/Fixtures/block-json
 
   plugin-check-build:
-    name: Plugin Check fixture build
+    name: Build the Plugin Check fixture
     runs-on: ubuntu-latest
     timeout-minutes: 30
     permissions:
@@ -140,7 +138,7 @@ jobs:
           retention-days: 1
 
   plugin-check:
-    name: Plugin Check
+    name: Run Plugin Check
     needs: plugin-check-build
     # The fixture fails Plugin Check unless the GitHub profile skips its Update URI and its missing readme.txt and the scan skips vendor-prefixed/.
     permissions:

.github/workflows/reusable-block-json-check.yml

@@ -4,7 +4,7 @@ on:
   workflow_call:
     inputs:
       project-path:
-        description: 'Path to the project (relative to repo root)'
+        description: 'Path to the project, relative to the repository root.'
         type: string
         required: false
         default: '.'
@@ -33,7 +33,7 @@ jobs:
           sparse-checkout: node/block-json
           persist-credentials: false
 
-      - name: Setup Node.js
+      - name: Set up Node.js
         uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
           node-version: '26'
@@ -47,14 +47,13 @@ jobs:
         env:
           AJV: ${{ github.workspace }}/.block-json-tools/node/block-json/node_modules/.bin/ajv
         run: |
-          # Validate one file per -d invocation; a single joined string breaks multi-block plugins.
+          # Each file takes its own -d argument, so a plugin with several blocks validates every one.
           mapfile -d '' files < <(find . -path ./node_modules -prune -o -path ./vendor -prune -o -path ./.block-json-tools -prune -o -name 'block.json' -print0)
           if [ "${#files[@]}" -eq 0 ]; then
             echo "No block.json files found — nothing to validate."
             exit 0
           fi
-          # schemas.wp.org publishes no versioned block.json path; trunk is the only (mutable) schema source.
-          # ajv-cli reads -s from disk and picks its parser from the extension, so fetch to a .json path; curl -f fails this check on a schemas.wp.org outage.
+          # The trunk schema, the only block.json schema schemas.wp.org publishes, is fetched to a .json path, because ajv-cli reads -s from disk and picks its parser from the extension, and curl -f fails the check during an outage.
           schema="$(mktemp -d)/schema.json"
           curl -fsSL https://schemas.wp.org/trunk/block.json -o "$schema"
           for file in "${files[@]}"; do

.github/workflows/reusable-codeql.yml

@@ -4,8 +4,8 @@ on:
   workflow_call:
     inputs:
       languages:
-        # CodeQL ships no PHP analyzer; PHP is statically analysed by PHPStan in the Quality workflow.
-        description: 'Non-empty JSON array of CodeQL languages'
+        # CodeQL has no PHP analyzer, so PHPStan covers PHP.
+        description: 'Non-empty JSON array of CodeQL languages.'
         type: string
         required: false
         default: '["actions"]'
@@ -19,7 +19,7 @@ jobs:
     timeout-minutes: 30
     permissions: {}
     steps:
-      # An empty JSON array expands to zero matrix jobs and reports success — a silent skip of the security scan.
+      # An empty JSON array expands to zero matrix jobs that report success, silently skipping the security scan.
       - name: Reject an empty languages array
         env:
           LANGUAGES: ${{ inputs.languages }}
@@ -97,10 +97,12 @@ jobs:
         with:
           persist-credentials: false
 
-      - uses: github/codeql-action/init@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
         with:
           languages: ${{ matrix.language }}
 
-      - uses: github/codeql-action/analyze@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
+      - name: Run the CodeQL analysis
+        uses: github/codeql-action/analyze@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
         with:
           category: '/language:${{ matrix.language }}'

.github/workflows/reusable-php-lint.yml

@@ -4,7 +4,7 @@ on:
   workflow_call:
     inputs:
       scripts:
-        description: 'Non-empty JSON array of composer scripts; each runs as its own parallel job.'
+        description: 'Non-empty JSON array of Composer scripts; each runs as its own parallel job.'
         type: string
         required: true
       php-version:
@@ -13,7 +13,7 @@ on:
         required: false
         default: '8.5'
       project-path:
-        description: 'Path to the project (relative to repo root).'
+        description: 'Path to the project, relative to the repository root.'
         type: string
         required: false
         default: '.'
@@ -32,7 +32,7 @@ jobs:
     timeout-minutes: 30
     permissions: {}
     steps:
-      # An empty JSON array expands to zero matrix jobs and reports success — a silent skip of the lint.
+      # An empty JSON array expands to zero matrix jobs that report success, silently skipping the lint.
       - name: Reject an empty scripts array
         env:
           SCRIPTS: ${{ inputs.scripts }}
@@ -43,7 +43,7 @@ jobs:
           fi
 
   composer-validate:
-    name: composer validate
+    name: Validate composer.json
     runs-on: ubuntu-latest
     timeout-minutes: 30
     permissions:
@@ -52,17 +52,18 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0
+      - name: Set up PHP
+        uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0
         with:
           php-version: ${{ inputs.php-version }}
           coverage: none
           tools: composer:v2
-      - name: composer validate --strict
+      - name: Run composer validate --strict
         working-directory: ${{ inputs.project-path }}
         run: composer validate --strict
 
   lint:
-    name: ${{ matrix.script }}
+    name: Run ${{ matrix.script }}
     needs: validate-inputs
     runs-on: ubuntu-latest
     timeout-minutes: 30
@@ -76,16 +77,18 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0
+      - name: Set up PHP
+        uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0
         with:
           php-version: ${{ inputs.php-version }}
           coverage: none
           tools: composer:v2
-      - uses: ramsey/composer-install@65e4f84970763564f46a70b8a54b90d033b3bdda # 4.0.0
+      - name: Install Composer dependencies
+        uses: ramsey/composer-install@65e4f84970763564f46a70b8a54b90d033b3bdda # 4.0.0
         with:
           working-directory: ${{ inputs.project-path }}
           composer-options: ${{ inputs.composer-options }}
-      - name: composer ${{ matrix.script }}
+      - name: Run composer ${{ matrix.script }}
         working-directory: ${{ inputs.project-path }}
         env:
           SCRIPT: ${{ matrix.script }}

.github/workflows/reusable-php-syntax-check.yml

@@ -4,12 +4,12 @@ on:
   workflow_call:
     inputs:
       project-path:
-        description: 'Path to the project (relative to repo root)'
+        description: 'Path to the project, relative to the repository root.'
         type: string
         required: false
         default: '.'
       php-versions:
-        description: 'Non-empty JSON array of PHP versions to check (e.g. [\"8.5\",\"8.6\"])'
+        description: 'Non-empty JSON array of PHP versions to check, such as ["8.5", "8.6"].'
         type: string
         required: false
         default: '["8.5", "8.6"]'
@@ -33,7 +33,7 @@ jobs:
     timeout-minutes: 30
     permissions: {}
     steps:
-      # An empty JSON array expands to zero matrix jobs and reports success — a silent skip of the syntax check.
+      # An empty JSON array expands to zero matrix jobs that report success, silently skipping the syntax check.
       - name: Reject an empty php-versions array
         env:
           PHP_VERSIONS: ${{ inputs.php-versions }}
@@ -53,7 +53,7 @@ jobs:
           fi
 
   syntax:
-    name: Syntax (PHP ${{ matrix.php-version }})
+    name: Check syntax (PHP ${{ matrix.php-version }})
     needs: validate-inputs
     runs-on: ubuntu-latest
     timeout-minutes: 30
@@ -76,7 +76,7 @@ jobs:
         with:
           name: ${{ inputs.artifact }}
 
-      - name: Setup PHP
+      - name: Set up PHP
         uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0
         with:
           php-version: ${{ matrix.php-version }}