chore: mark action bundles as generated and cover extract-version

The four JavaScript actions run from a committed dist/index.js, so every runtime
dependency is bundled into it. That puts large generated artifacts in the middle
of every review: #79 changed 28 lines of package.json and pnpm-lock.yaml plus
3,176 lines of rebuilt bundle, so 99% of that review was generated output.

Marks them as generated in .gitattributes so they collapse in pull request
diffs. Reviewers see the source changes, and check_dist:required continues to
guarantee that the collapsed output is exactly what that source compiles to,
which is what makes collapsing it safe rather than reckless.

Adds extract-version to the check_dist matrix. It is a node24 action with an
856K bundle that was not covered, so a stale bundle there went unverified, and
it is the action release workflows use to read the version being published. Its
committed bundle is currently in sync, so this adds coverage without requiring
a rebuild.

Documents both in CONTRIBUTING.md, including the part that is easy to miss: a
dependency fix without rebuilt bundles does not change what runs, because the
lockfile is not consulted when GitHub executes an action. Adds a matching
convention to the README, since this repo documents conventions for other
repositories too.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: marc0olo

.gitattributes

@@ -0,0 +1,4 @@
+# Action bundles are generated by `pnpm build` and verified by check_dist:required.
+# Marking them as generated collapses them in pull request diffs, so reviewers see
+# the source changes instead of thousands of lines of bundled output.
+actions/*/dist/** linguist-generated=true

.github/CONTRIBUTING.md

@@ -119,3 +119,15 @@ pnpm build
 ```
 
 The GitHub actions pipeline will attempt to build the actions and check if there are any differences between the built files and those that are committed to the repository. If there are any differences, the pipeline will fail.
+
+### Why the bundles are committed
+
+GitHub runs a JavaScript action (`using: node24`) straight from its committed `dist/index.js`. It does not install dependencies or run a build first, so every runtime dependency is bundled into that one file.
+
+This has a consequence that is easy to miss: updating a bundled dependency in `package.json` and `pnpm-lock.yaml` changes nothing about what actually runs until the bundles are rebuilt. A dependency fix that is not accompanied by rebuilt bundles is not applied.
+
+The bundles are marked as generated in `.gitattributes`, so they are collapsed in pull request diffs. Review the source changes rather than the bundled output; the `check_dist:required` job is what guarantees the committed bundles are exactly what that source compiles to.
+
+### When an automated dependency update fails the check
+
+Automated dependency updates change `package.json` and `pnpm-lock.yaml` but cannot rebuild the bundles, so `check_dist:required` fails on those pull requests. Check the branch out, run `pnpm build`, and commit the rebuilt bundles to it.

.github/workflows/self-check-dist.yaml

@@ -14,7 +14,8 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        action_name: ['create-pr', 'assemble-docs', 'submit-docs']
+        action_name:
+          ['create-pr', 'assemble-docs', 'submit-docs', 'extract-version']
     steps:
       - name: Checkout repository
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

README.md

@@ -49,6 +49,18 @@ Example:
 name: my_action:required
 ```
 
+### Generated files
+
+A JavaScript action (`using: node24`) is executed by GitHub straight from the committed file its `main` points at, with no install or build step beforehand. Its dependencies therefore have to be committed too, which is why they are bundled into a single `dist/index.js`.
+
+Mark that output as generated so it collapses in pull request diffs instead of burying the source changes:
+
+```gitattributes
+actions/*/dist/** linguist-generated=true
+```
+
+Pair it with a job that rebuilds the bundles and fails on any difference. That check is what makes collapsing the diff safe, because it proves the committed output is exactly what the reviewed source compiles to.
+
 ## Locking Versions
 
 When referencing 3rd party actions, use a specific commit SHA to lock the version. This ensures that the action will not change unexpectedly, which could lead to breaking changes in your workflows.