From b39bb70cc8282ea9c7ccc06b90cc9f978b8b8516 Mon Sep 17 00:00:00 2001 From: Jordi Kroon Date: Wed, 29 Apr 2026 20:44:22 +0200 Subject: [PATCH 1/5] add docbook-cs linting --- .github/workflows/check-whitespace.yml | 29 ---------- .github/workflows/docbook-cs.yml | 79 ++++++++++++++++++++++++++ docbookcs.xml | 35 ++++++++++++ 3 files changed, 114 insertions(+), 29 deletions(-) delete mode 100644 .github/workflows/check-whitespace.yml create mode 100644 .github/workflows/docbook-cs.yml create mode 100644 docbookcs.xml diff --git a/.github/workflows/check-whitespace.yml b/.github/workflows/check-whitespace.yml deleted file mode 100644 index 91c5e6419562..000000000000 --- a/.github/workflows/check-whitespace.yml +++ /dev/null @@ -1,29 +0,0 @@ -name: check-whitespace - -# Get the repository with all commits to ensure that we can analyze -# all of the commits contributed via the Pull Request. -# Process `git log --check` output to extract just the check errors. -# Exit with failure upon white-space issues. - -on: - pull_request: - types: [opened, synchronize] - -permissions: - contents: read - -jobs: - check-whitespace: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v6 - with: - fetch-depth: 0 - - - run: | - git config --global user.name "check-whitespace" - git config --global user.email "check-whitespace@example.com" - - run: git checkout ${{github.event.pull_request.base.sha}} - - run: git merge --squash ${{github.event.pull_request.head.sha}} - - run: git commit -m "Squashed" - - run: git log --check HEAD^..HEAD diff --git a/.github/workflows/docbook-cs.yml b/.github/workflows/docbook-cs.yml new file mode 100644 index 000000000000..c64e7a3efce2 --- /dev/null +++ b/.github/workflows/docbook-cs.yml @@ -0,0 +1,79 @@ +name: DocBook Lint + +on: + push: + branches: [master] + pull_request: + branches: [master] + +jobs: + docbook-cs: + name: DocBook Style Check + runs-on: ubuntu-latest + + steps: + - name: Checkout doc-en + uses: actions/checkout@v4 + with: + ref: ${{ github.event.pull_request.head.sha }} + path: en + fetch-depth: 0 + + - name: Checkout php/doc-base + uses: actions/checkout@v4 + with: + path: doc-base + repository: php/doc-base + + - name: Setup PHP + uses: shivammathur/setup-php@v2 + with: + php-version: '8.5' + extensions: dom, libxml, simplexml + + - name: Build documentation + run: php doc-base/configure.php --disable-libxml-check --enable-xml-details --redirect-stderr-to-stdout --with-lang=en + + - name: Install docbook-cs + working-directory: en + run: composer require jordikroon/docbook-cs + + - name: Fetch base branch + working-directory: en + run: git fetch origin ${{ github.base_ref }} + + - name: Run docbook-cs with diff + working-directory: en + run: | + set -o pipefail + git diff origin/${{ github.base_ref }}...HEAD | vendor/bin/docbook-cs \ + --report=checkstyle \ + --diff \ + --no-colors > docbook-report.xml + + - name: Upload report + if: always() + uses: actions/upload-artifact@v4 + with: + name: docbook-report + path: en/docbook-report.xml + + - name: Setup reviewdog + if: always() + uses: reviewdog/action-setup@v1 + with: + reviewdog_version: latest + + - name: Report violations via reviewdog + if: always() + working-directory: en + env: + REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + cat docbook-report.xml | reviewdog \ + -f=checkstyle \ + -name="docbook-cs" \ + -reporter=github-pr-check \ + -level=error \ + -fail-level=any \ + -filter-mode=nofilter diff --git a/docbookcs.xml b/docbookcs.xml new file mode 100644 index 000000000000..b350b7233e7a --- /dev/null +++ b/docbookcs.xml @@ -0,0 +1,35 @@ + + + + + en + doc-base + + + + + + + + + + + . + + + + contributors.ent + extensions.ent + language-defs.ent + language-snippets.ent + ../doc-base/entities/ + ../doc-base/temp/file-entities.ent + ../doc-base/temp/file-entities + + + + */wkhtmltox/bits/* + output/* + + + From b3296894a279c2f6f21883a6d0c7a51b6267c9ce Mon Sep 17 00:00:00 2001 From: Jordi Kroon Date: Wed, 29 Apr 2026 22:58:32 +0200 Subject: [PATCH 2/5] refactor docbook-cs workflow --- .github/workflows/docbook-cs.yml | 136 +++++++++++++++++++------------ 1 file changed, 84 insertions(+), 52 deletions(-) diff --git a/.github/workflows/docbook-cs.yml b/.github/workflows/docbook-cs.yml index c64e7a3efce2..27d18de841e7 100644 --- a/.github/workflows/docbook-cs.yml +++ b/.github/workflows/docbook-cs.yml @@ -1,79 +1,111 @@ -name: DocBook Lint +# https://docs.github.com/en/actions + +name: "DocBook Lint" on: push: - branches: [master] + branches: + - "master" pull_request: - branches: [master] + branches: + - "master" + +permissions: + contents: "read" + +concurrency: + group: "${{ github.workflow }}-${{ github.ref }}" + cancel-in-progress: true jobs: docbook-cs: - name: DocBook Style Check - runs-on: ubuntu-latest + name: "DocBook Style Check" + runs-on: "ubuntu-latest" + + strategy: + matrix: + language: + - "en" steps: - - name: Checkout doc-en - uses: actions/checkout@v4 + - name: "Checkout php/doc-${{ matrix.language }}" + uses: "actions/checkout@v6" with: - ref: ${{ github.event.pull_request.head.sha }} - path: en - fetch-depth: 0 + ref: "${{ github.event.pull_request.head.sha }}" + path: "${{ matrix.language }}" + fetch-depth: 50 - - name: Checkout php/doc-base - uses: actions/checkout@v4 + - name: "Checkout php/doc-base" + uses: "actions/checkout@v6" with: - path: doc-base - repository: php/doc-base + path: "doc-base" + repository: "php/doc-base" + + - name: "Fetch base branch with merge-base" + working-directory: "${{ matrix.language }}" + run: | + git fetch origin ${{ github.base_ref }} --depth=50 + # Deepen until we find the merge-base (handles long-lived PRs) + for i in 1 2 3 4 5; do + if git merge-base origin/${{ github.base_ref }} HEAD >/dev/null 2>&1; then + break + fi + git fetch --deepen=100 origin ${{ github.base_ref }} + done - - name: Setup PHP - uses: shivammathur/setup-php@v2 + - name: "Setup PHP" + uses: "shivammathur/setup-php@v2" with: - php-version: '8.5' - extensions: dom, libxml, simplexml + php-version: "8.5" + extensions: "dom, libxml, simplexml" + tools: composer:v2 - - name: Build documentation - run: php doc-base/configure.php --disable-libxml-check --enable-xml-details --redirect-stderr-to-stdout --with-lang=en + - name: "Build documentation" + run: | + php doc-base/configure.php \ + --disable-libxml-check \ + --enable-xml-details \ + --redirect-stderr-to-stdout \ + --with-lang=${{ matrix.language }} - - name: Install docbook-cs - working-directory: en + - name: "Install docbook-cs" + working-directory: "${{ matrix.language }}" run: composer require jordikroon/docbook-cs - - name: Fetch base branch - working-directory: en - run: git fetch origin ${{ github.base_ref }} - - - name: Run docbook-cs with diff - working-directory: en + - name: "Run docbook-cs with diff" + working-directory: "${{ matrix.language }}" run: | set -o pipefail git diff origin/${{ github.base_ref }}...HEAD | vendor/bin/docbook-cs \ --report=checkstyle \ --diff \ - --no-colors > docbook-report.xml - - - name: Upload report - if: always() - uses: actions/upload-artifact@v4 - with: - name: docbook-report - path: en/docbook-report.xml + --no-colors > docbook-report.xml || true - - name: Setup reviewdog - if: always() - uses: reviewdog/action-setup@v1 + - name: "Upload report" + if: ${{ ! cancelled() }} + uses: "actions/upload-artifact@v7" with: - reviewdog_version: latest + name: "docbook-report" + path: "${{ matrix.language }}/docbook-report.xml" - - name: Report violations via reviewdog - if: always() - working-directory: en - env: - REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} + - name: "Annotate PR with violations" + if: ${{ ! cancelled() }} + working-directory: "${{ matrix.language }}" run: | - cat docbook-report.xml | reviewdog \ - -f=checkstyle \ - -name="docbook-cs" \ - -reporter=github-pr-check \ - -level=error \ - -fail-level=any \ - -filter-mode=nofilter + php -r ' + if (!file_exists("docbook-report.xml")) exit(0); + $xml = simplexml_load_file("docbook-report.xml"); + $hasErrors = false; + foreach ($xml->file as $file) { + $name = (string)$file["name"]; + foreach ($file->error as $error) { + $hasErrors = true; + $line = (string)$error["line"]; + $msg = (string)$error["message"]; + $sev = (string)$error["severity"]; + $cmd = $sev === "error" ? "error" : "warning"; + echo "::{$cmd} file={$name},line={$line}::{$msg}\n"; + } + } + exit($hasErrors ? 1 : 0); + ' From 5d4c2d50ebe598c0282f90412f0631dd224d9b0c Mon Sep 17 00:00:00 2001 From: Jordi Kroon Date: Wed, 29 Apr 2026 23:13:17 +0200 Subject: [PATCH 3/5] refactor docbook-cs workflow --- .github/workflows/docbook-cs.yml | 38 ++++++++++++++++++++++++++------ 1 file changed, 31 insertions(+), 7 deletions(-) diff --git a/.github/workflows/docbook-cs.yml b/.github/workflows/docbook-cs.yml index 27d18de841e7..8cd3210b3489 100644 --- a/.github/workflows/docbook-cs.yml +++ b/.github/workflows/docbook-cs.yml @@ -93,19 +93,43 @@ jobs: working-directory: "${{ matrix.language }}" run: | php -r ' - if (!file_exists("docbook-report.xml")) exit(0); + if (!file_exists("docbook-report.xml")) { + echo "No report found.\n"; + exit(0); + } + $xml = simplexml_load_file("docbook-report.xml"); - $hasErrors = false; + + $errorCount = 0; + $warningCount = 0; + foreach ($xml->file as $file) { $name = (string)$file["name"]; + + echo "::group::File: {$name}\n"; + foreach ($file->error as $error) { - $hasErrors = true; $line = (string)$error["line"]; - $msg = (string)$error["message"]; - $sev = (string)$error["severity"]; - $cmd = $sev === "error" ? "error" : "warning"; + $msg = (string)$error["message"]; + $sev = (string)$error["severity"]; + $cmd = $sev === "error" ? "error" : "warning"; + + if ($sev === "error") { + $errorCount++; + } else { + $warningCount++; + } + + // Human-readable log + echo "[{$sev}] {$name}:{$line} {$msg}\n"; + + // GitHub annotation echo "::{$cmd} file={$name},line={$line}::{$msg}\n"; } + + echo "::endgroup::\n"; } - exit($hasErrors ? 1 : 0); + + echo "\nSummary: {$errorCount} error(s), {$warningCount} warning(s)\n"; + exit($errorCount > 0 ? 1 : 0); ' From 9e280260a9a9b057e8814624a8eb41c8ef1ca93b Mon Sep 17 00:00:00 2001 From: Jordi Kroon Date: Thu, 30 Apr 2026 23:01:17 +0200 Subject: [PATCH 4/5] pin docbook-cs dependencies and add cs2pr --- .github/workflows/docbook-cs.yml | 45 ++------------------------------ 1 file changed, 2 insertions(+), 43 deletions(-) diff --git a/.github/workflows/docbook-cs.yml b/.github/workflows/docbook-cs.yml index 8cd3210b3489..0016d89123bd 100644 --- a/.github/workflows/docbook-cs.yml +++ b/.github/workflows/docbook-cs.yml @@ -70,7 +70,7 @@ jobs: - name: "Install docbook-cs" working-directory: "${{ matrix.language }}" - run: composer require jordikroon/docbook-cs + run: composer require jordikroon/docbook-cs:^1.1 staabm/annotate-pull-request-from-checkstyle:^1.8 - name: "Run docbook-cs with diff" working-directory: "${{ matrix.language }}" @@ -91,45 +91,4 @@ jobs: - name: "Annotate PR with violations" if: ${{ ! cancelled() }} working-directory: "${{ matrix.language }}" - run: | - php -r ' - if (!file_exists("docbook-report.xml")) { - echo "No report found.\n"; - exit(0); - } - - $xml = simplexml_load_file("docbook-report.xml"); - - $errorCount = 0; - $warningCount = 0; - - foreach ($xml->file as $file) { - $name = (string)$file["name"]; - - echo "::group::File: {$name}\n"; - - foreach ($file->error as $error) { - $line = (string)$error["line"]; - $msg = (string)$error["message"]; - $sev = (string)$error["severity"]; - $cmd = $sev === "error" ? "error" : "warning"; - - if ($sev === "error") { - $errorCount++; - } else { - $warningCount++; - } - - // Human-readable log - echo "[{$sev}] {$name}:{$line} {$msg}\n"; - - // GitHub annotation - echo "::{$cmd} file={$name},line={$line}::{$msg}\n"; - } - - echo "::endgroup::\n"; - } - - echo "\nSummary: {$errorCount} error(s), {$warningCount} warning(s)\n"; - exit($errorCount > 0 ? 1 : 0); - ' + run: vendor/bin/cs2pr docbook-report.xml --colorize --prepend-filename From 122c89a63defc5144659a8c2da5c95cb530362d1 Mon Sep 17 00:00:00 2001 From: Jordi Kroon Date: Thu, 30 Apr 2026 23:02:26 +0200 Subject: [PATCH 5/5] update docbook-cs XML namespace and add schema validation --- docbookcs.xml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docbookcs.xml b/docbookcs.xml index b350b7233e7a..714c2a9f2a3f 100644 --- a/docbookcs.xml +++ b/docbookcs.xml @@ -1,5 +1,8 @@ - + en