ci: cut a docs version on release, only when the docs changed

[oojacoboo]

Cuts a Docusaurus docs version on release, but only when the documentation actually changed.

Why

Versioning is a manual docusaurus docs:version commit today, and it has drifted:

Release	Snapshot cut?
8.3.1	no, though it changed troubleshooting.md by 39 lines
8.3.0	yes
8.2.0	yes
8.1.3 / 8.1.2 / 8.1.1 / 8.1.0	no
8.0.0	yes

versions.json currently stops at 8.3.0 while 8.3.1 is released, so a reader on the 8.3.x docs is
reading a snapshot that predates the fixes shipped in 8.3.1.

The rule

Cut a version if, and only if, website/docs differs from the most recent snapshot.

The version number decides nothing. A patch release that changed documentation gets a snapshot, and
a major release that changed none does not, because a snapshot identical to the one before it is
just noise in the version picker. That is the whole policy; the other two guards are safety rather
than policy:

• a version already present in versions.json is skipped, so re-running is harmless
• a tag that is not a plain X.Y.Z is skipped, which keeps prereleases out of the picker

Comparing against the snapshot, not the tag

The diff is taken against website/versioned_docs/version-<previous>/ rather than against the
previous release's git tag, and the distinction is load-bearing.

The 8.3.0 snapshot was committed in 0335865, which also carried documentation edits, after v8.3.0
had already been tagged. Diffing website/docs against the tag therefore reports 7 changed
files; diffing against the snapshot reports 4. The three-file difference is content the snapshot
already contains. Since the snapshot is what readers actually see, the snapshot is the correct
baseline, and it does not depend on tags existing or on when they were placed.

Output

The run opens a pull request rather than pushing to master. A cut is roughly 41 files and 6,000
lines, which is worth a human glance, and a PR avoids both the protected-branch question and
re-triggering doc_generation.yml from a push the workflow itself made. add-paths restricts the
commit to versions.json, versioned_docs/ and versioned_sidebars/.

The site is built from the generated snapshot before the PR is opened, so a snapshot that does not
compile fails the run instead of landing.

Testing

Verified locally against this repository:

• docusaurus docs:version 8.4.0 produces 41 doc files, version-8.4.0-sidebars.json and the
  versions.json entry, and touches nothing outside the three allowlisted paths
• the site builds clean with the extra version present
• the decision logic was exercised across the release/dispatch/force/prerelease combinations, and
  against the real 8.3.0 snapshot for both the changed and unchanged cases

workflow_dispatch is available to cut a version by hand, with force to snapshot even when the
docs are unchanged.

Note on inputs

The release tag and the dispatch input reach the shell through env: rather than ${{ }}
interpolation, so a tag containing shell syntax is data rather than script. The X.Y.Z check runs
before the value is used for anything.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.72%. Comparing base (53f9d49) to head (6e3bb0f).
⚠️ Report is 164 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff              @@
##             master     #821      +/-   ##
============================================
- Coverage     95.72%   91.72%   -4.01%     
- Complexity     1773     2025     +252     
============================================
  Files           154      198      +44     
  Lines          4586     5436     +850     
============================================
+ Hits           4390     4986     +596     
- Misses          196      450     +254     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.