ci: add per-PR XML structure check against doc-en

[lacatoire]

Adds a GitHub Actions workflow that runs on every pull request and checks that the block structure of modified XML files stays aligned with the corresponding doc-en file.

How it works

• Triggered on pull_request events targeting master
• Collects the list of .xml files changed in the PR
• For each file, reads the EN-Revision hash it declares and fetches doc-en at that exact revision
• Compares the element skeleton of both files (tag names and structural attributes, not prose)
• Emits ::error annotations in the PR if a divergence is found
• A file that lags behind sync is compared against the EN version it actually translated, so it does not produce false positives

Prior art

This check is already in use in doc-fr, doc-ru, doc-es, and doc-it. There is also an ongoing initiative in doc-base to provide reusable workflows that all doc-* repos can share.

[KentarouTakeda]

Thanks. It does find real problems: 11 of the 22 distinct annotations it produced in doc-ru are genuine <para> / <simpara> drift. But I'm declining it for doc-ja.

The description says a lagging file is compared against the English it actually translated, so it cannot false-positive. That holds for ordinary commits, not for [skip-revcheck] ones — there, translations mirror the markup without bumping EN-Revision, so the script compares the new translation against the old English.

Measured on doc-ja master: 346 files flagged, but only 81 still diverge when compared against doc-en HEAD instead. So 265 — 77% — are false positives, and all 265 also appear in #413's failure set. As noted there, doc-base documents this [skip-revcheck] behaviour as a defect (backport.php, php/doc-base#181), so the current semantics are a moving target.

On scope: doc-en's docbook-cs.yaml runs git diff BASE...HEAD | docbook-cs --diff, so only violations inside the changed hunks fail. This PR compares whole-file skeletons, so a PR fails on drift it did not introduce — php/doc-it#70, opened 2025-02-09, is currently red on a security/database.xml divergence that long predates it.

With php/doc-en#5672 (removing SimparaSniff) still open and php/docbook-cs#35 adding --fix, enforcing this per file also seems early.

Two smaller things: two annotations print the same signature on both sides, because the depth prefix is compared but trimmed from the message; and the translator-credits guard expects xml:id="translators…", which doc-ja does not use.

Closing. php/docbook-cs looks like the right home for this — you already have #16, #17 and #22 there, it is wired into doc-en, and --diff avoids the pre-existing-drift problem by construction. The 81 genuine divergences are useful to us either way; we will handle those separately.