chore: import upstream snapshot with attribution

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,62 @@
+# PaddleOCR
+
+name: 🐛 Bug Report
+description: Problems with PaddleOCR
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for submitting a PaddleOCR 🐛 Bug Report!
+
+  - type: checkboxes
+    attributes:
+      label: 🔎 Search before asking
+      description: >
+        Please search the PaddleOCR [Docs](https://paddlepaddle.github.io/PaddleOCR/), [Issues](https://github.com/PaddlePaddle/PaddleOCR/issues) and [Discussions](https://github.com/PaddlePaddle/PaddleOCR/discussions) to see if a similar bug report already exists.
+      options:
+        - label: I have searched the PaddleOCR [Docs](https://paddlepaddle.github.io/PaddleOCR/) and found no similar bug report.
+          required: true
+        - label: I have searched the PaddleOCR [Issues](https://github.com/PaddlePaddle/PaddleOCR/issues) and found no similar bug report.
+          required: true
+        - label: I have searched the PaddleOCR [Discussions](https://github.com/PaddlePaddle/PaddleOCR/discussions) and found no similar bug report.
+          required: true
+
+  - type: textarea
+    attributes:
+      label: 🐛 Bug (问题描述)
+      description: Provide console output with error messages and/or screenshots of the bug. (请提供详细报错信息或者截图)
+      placeholder: |
+        💡 ProTip! Include as much information as possible (screenshots, logs, tracebacks etc.) to receive the most helpful response.
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: 🏃‍♂️ Environment (运行环境)
+      description: Please specify the software and hardware you used to produce the bug. (请给出详细依赖包信息，便于复现问题)
+      placeholder: |
+        ```bash
+        OS                  macOS-13.5.2
+        Environment         Jupyter
+        Python              3.11.2
+        PaddleOCR           2.8.1
+        Install             git
+        RAM                 16.00 GB
+        CPU                 Apple M2
+        CUDA                None
+        ```
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: 🌰 Minimal Reproducible Example (最小可复现问题的Demo)
+      description: >
+        When asking a question, people will be better able to provide help if you provide code that they can easily understand and use to **reproduce** the problem.
+        This is referred to by community members as creating a [minimal reproducible example](https://stackoverflow.com/help/minimal-reproducible-example). (请务必提供该Demo，这样节省大家时间)
+      placeholder: |
+        ```bash
+        # Code to reproduce your issue here
+        ```
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 🙏 Q&A
+    url: https://github.com/PaddlePaddle/PaddleOCR/discussions/categories/q-a
+    about: Ask the community for help
+  - name: 💡 Feature requests and ideas
+    url: https://github.com/PaddlePaddle/PaddleOCR/discussions/categories/ideas
+    about: Share ideas for new features
+  - name: 🙌 Show and tell
+    url: https://github.com/PaddlePaddle/PaddleOCR/discussions/categories/show-and-tell
+    about: Show off something you've made

.github/actions/detect-docs-only/action.yml

@@ -0,0 +1,55 @@
+name: Detect Docs-Only Change
+description: >
+  Output docs_only=true if every changed file in the current pull_request
+  matches docs/**, **/*.md, or .github/**. On push or workflow_dispatch,
+  always output docs_only=false.
+outputs:
+  docs_only:
+    description: "true if change is docs-only, otherwise false"
+    value: ${{ steps.compute.outputs.docs_only }}
+runs:
+  using: composite
+  steps:
+    - id: compute
+      shell: bash
+      env:
+        GITHUB_EVENT_NAME: ${{ github.event_name }}
+        GITHUB_BASE_REF: ${{ github.base_ref }}
+      run: |
+        set -euo pipefail
+        if [ "${GITHUB_EVENT_NAME}" != "pull_request" ]; then
+          echo "docs_only=false" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+        git fetch origin "${GITHUB_BASE_REF}" --depth=1 >/dev/null 2>&1 || true
+        CHANGED_FILES="$(git diff --name-only "origin/${GITHUB_BASE_REF}...HEAD")"
+        # >>> matcher-begin
+        shopt -s globstar extglob nullglob
+        is_docs_only() {
+          local files="$1"
+          if [ -z "$files" ]; then
+            echo "false"; return 0
+          fi
+          while IFS= read -r f; do
+            [ -z "$f" ] && continue
+            case "$f" in
+              docs/*) ;;
+              .github/*) ;;
+              *.md) ;;
+              *)
+                # also accept nested */**/*.md via case glob
+                case "$f" in
+                  */*.md) ;;
+                  *) echo "false"; return 0 ;;
+                esac
+                ;;
+            esac
+          done <<< "$files"
+          echo "true"
+        }
+        result="$(is_docs_only "${CHANGED_FILES}")"
+        if [ -n "${GITHUB_OUTPUT:-}" ] && [ "${GITHUB_OUTPUT}" != "/dev/null" ]; then
+          echo "docs_only=${result}" >> "$GITHUB_OUTPUT"
+        fi
+        echo "${result}"
+        # <<< matcher-end

.github/dependabot.yml

@@ -0,0 +1,13 @@
+# Keep GitHub Actions up to date with GitHub's Dependabot...
+# https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot
+# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#package-ecosystem
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    groups:
+      github-actions:
+        patterns:
+          - "*"  # Group all Actions updates into a single larger pull request
+    schedule:
+      interval: weekly

.github/workflows/build_publish_develop_docs.yml

@@ -0,0 +1,39 @@
+name: Build/Publish Develop Docs
+on:
+  push:
+    branches:
+      - master
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v5
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mike mkdocs-material jieba mkdocs-git-revision-date-localized-plugin mkdocs-git-committers-plugin-2 mkdocs-static-i18n markdown-callouts
+      - name: Check docs GitHub source links
+        run: python tools/check_docs_github_links.py --repo-slug PaddlePaddle/PaddleOCR --forbidden-ref main --forbidden-ref master
+      - name: Resolve docs GitHub source refs
+        run: python tools/resolve_doc_github_refs.py --placeholder '{{PADDLEOCR_GITHUB_REF}}' --source-ref "${REF_NAME}"
+        env:
+          REF_NAME: ${{ github.ref_name }}
+      - run: |
+          git fetch origin gh-pages --depth=1
+          mike deploy --push --update-aliases main latest
+        env:
+          DOCS_EDIT_URI: edit/${{ github.ref_name }}/docs/

.github/workflows/build_publish_release_docs.yml

@@ -0,0 +1,41 @@
+name: Build/Publish Release Docs
+on:
+  push:
+    tags:
+      - v*
+
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v5
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mike mkdocs-material jieba mkdocs-git-revision-date-localized-plugin mkdocs-git-committers-plugin-2 mkdocs-static-i18n markdown-callouts
+      - name: Check docs GitHub source links
+        run: python tools/check_docs_github_links.py --repo-slug PaddlePaddle/PaddleOCR --forbidden-ref main --forbidden-ref master
+      - name: Resolve docs GitHub source refs
+        run: python tools/resolve_doc_github_refs.py --placeholder '{{PADDLEOCR_GITHUB_REF}}' --source-ref "${REF_NAME}"
+        env:
+          REF_NAME: ${{ github.ref_name }}
+      - run: |
+          git fetch origin gh-pages --depth=1
+          mike deploy --push "${REF_NAME}"
+
+        env:
+          REF_NAME: ${{ github.ref_name }}
+          DOCS_EDIT_URI: blob/${{ github.ref_name }}/docs/

.github/workflows/close_inactive_issues.yml

@@ -0,0 +1,23 @@
+name: Close inactive issues
+on:
+  schedule:
+    - cron: "30 1 * * *"
+
+jobs:
+  close-issues:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/stale@v10
+        with:
+          days-before-issue-stale: 90
+          days-before-issue-close: 14
+          stale-issue-label: "stale"
+          stale-issue-message: "This issue is stale because it has been open for 90 days with no activity."
+          close-issue-message: "This issue was closed because it has been inactive for 14 days since being marked as stale."
+          days-before-pr-stale: -1
+          days-before-pr-close: -1
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+    

.github/workflows/codestyle.yml

@@ -0,0 +1,41 @@
+name: PaddleOCR Code Style Check
+
+# NOTE: Job name `check-code-style` is the required status check context
+# configured in branch protection. Do not rename without updating settings.
+
+on:
+  pull_request: {}
+  push:
+    branches: ['main', 'release/*']
+
+jobs:
+  check-code-style:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.ref }}
+          fetch-depth: 0
+      - id: detect
+        uses: ./.github/actions/detect-docs-only
+      - uses: actions/setup-python@v6
+        if: steps.detect.outputs.docs_only != 'true'
+        with:
+          python-version: '3.10'
+      - name: Cache Python dependencies
+        if: steps.detect.outputs.docs_only != 'true'
+        uses: actions/cache@v5
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+      - name: Install Dependencies for Python
+        if: steps.detect.outputs.docs_only != 'true'
+        run: |
+          python -m pip install --upgrade pip
+          pip install "clang-format==13.0.0"
+      - uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
+        if: steps.detect.outputs.docs_only != 'true'
+        with:
+          extra_args: '--all-files'

.github/workflows/docs_anchor_check.yml

@@ -0,0 +1,39 @@
+name: Docs Anchor Link Check
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'mkdocs-ci.yml'
+      - 'overrides/**'
+
+jobs:
+  check-anchor-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.x'
+
+      - uses: actions/cache@v5
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-mkdocs-${{ hashFiles('mkdocs.yml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-mkdocs-
+
+      - name: Install dependencies
+        run: pip install mike mkdocs-material jieba mkdocs-git-revision-date-localized-plugin mkdocs-git-committers-plugin-2 mkdocs-static-i18n markdown-callouts
+
+      - name: Resolve docs GitHub source refs
+        run: python tools/resolve_doc_github_refs.py --placeholder '{{PADDLEOCR_GITHUB_REF}}' --source-ref main
+
+      - name: Check for broken anchor links
+        env:
+          ENABLE_GIT_PLUGINS: 'false'
+        run: mkdocs build -f mkdocs-ci.yml

.github/workflows/link_check.yml

@@ -0,0 +1,42 @@
+name: Link Checker
+
+on:
+  repository_dispatch:
+  workflow_dispatch:
+  # push:
+  #   branches:
+  #     - main
+  # schedule:
+  #   - cron: "00 18 * * 6"
+
+jobs:
+  linkChecker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.x'
+
+      - name: Resolve docs GitHub source refs
+        run: python tools/resolve_doc_github_refs.py --placeholder '{{PADDLEOCR_GITHUB_REF}}' --source-ref main
+
+      - name: Link Checker
+        id: lychee
+        uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+        with:
+            args: --exclude 'docs/index/*.md' 'docs/update/*.md' --verbose --no-progress --max-redirects 8 'docs/**/*.md'
+            format: markdown
+            fail: false
+            output: lychee/results.md
+
+      - name: Create Issue From File
+        if: steps.lychee.outputs.exit_code != 0
+        uses: peter-evans/create-issue-from-file@fca9117c27cdc29c6c4db3b86c48e4115a786710 # v6
+        with:
+          title: Link Checker Report
+          content-filepath: ./lychee/results.md
+          labels: report, automated issue

.github/workflows/python_publish.yml

@@ -0,0 +1,39 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v6
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build==1.2.2
+    - name: Build package
+      run: python -m build
+    - name: Publish package
+      uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e  # v1.13.0
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_API_TOKEN }}

.github/workflows/test_gpu.yml

@@ -0,0 +1,117 @@
+name: PaddleOCR PR Tests GPU
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+  workflow_dispatch:
+env:
+  PR_ID: ${{ github.event.pull_request.number }}
+  COMMIT_ID: ${{ github.event.pull_request.head.sha || github.sha }}
+  work_dir: /workspace/PaddleOCR
+  PADDLENLP_ROOT: /workspace/PaddleOCR
+  TASK: paddleocr-CI-${{ github.event.pull_request.number }}
+  BRANCH: ${{ github.event.pull_request.base.ref }}
+  AGILE_COMPILE_BRANCH: ${{ github.event.pull_request.base.ref }}
+  DIR_NAME: ${{ github.repository }}
+permissions:
+  contents: read
+
+jobs:
+  detect-changes:
+    runs-on: ubuntu-latest
+    outputs:
+      docs_only: ${{ steps.detect.outputs.docs_only }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - id: detect
+        uses: ./.github/actions/detect-docs-only
+
+  test-pr-gpu-impl:
+    runs-on: [self-hosted, GPU-2Card-OCR]
+    needs: detect-changes
+    if: needs.detect-changes.outputs.docs_only != 'true'
+    steps:
+      - name: run test
+        env:
+          py_version: "3.10"
+          paddle_whl: https://paddle-qa.bj.bcebos.com/paddle-pipeline/Develop-GpuSome-LinuxCentos-Gcc82-Cuda118-Cudnn86-Trt85-Py310-CINN-Compile/latest/paddlepaddle_gpu-0.0.0-cp310-cp310-linux_x86_64.whl
+          docker_image: ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddle:latest-dev-cuda11.8-cudnn8.6-trt8.5-gcc82
+        run: |
+          work_dir=$RANDOM
+          mkdir $work_dir
+          cd $work_dir
+          git clone --depth=1 https://github.com/PaddlePaddle/PaddleOCR.git -b main
+          cd PaddleOCR
+          if [ -n "${PR_ID}" ]; then
+            git fetch origin pull/${PR_ID}/head:ci_build
+            git checkout ci_build
+          else
+            git fetch --depth=1 origin "${COMMIT_ID}"
+            git checkout "${COMMIT_ID}"
+          fi
+          docker run --gpus all --rm -i --name PaddleOCR_CI_$RANDOM \
+            --shm-size=128g --net=host \
+            -v $PWD:/workspace -w /workspace  \
+            -e "py_version=${py_version}" \
+            -e "paddle_whl=${paddle_whl}" \
+            ${docker_image} /bin/bash -c '
+            ldconfig;
+            nvidia-smi
+            df -hl
+
+            echo ${py_version}
+            rm -rf run_env
+            mkdir run_env
+            ln -s $(which python${py_version}) run_env/python
+            ln -s $(which python${py_version}) run_env/python3
+            ln -s $(which pip${py_version}) run_env/pip
+            export PATH=$PWD/run_env:${PATH}
+
+            git config --global --add safe.directory /workspace
+
+            python -m pip install paddlepaddle-gpu==3.1.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/
+            python -c "import paddle; paddle.version.show()"
+            python -m pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
+            python -m pip install pytest
+            if [ -f requirements.txt ]; then python -m pip install -r requirements.txt; fi
+            PADDLEX_SERIES=$(grep -oE "paddlex\[[^]]+\]>=[0-9]+\.[0-9]+" pyproject.toml | head -1 | grep -oE "[0-9]+\.[0-9]+")
+            if [ -z "$PADDLEX_SERIES" ]; then
+              echo "Failed to determine PaddleX version requirement from pyproject.toml" >&2
+              exit 1
+            fi
+            PADDLEX_BRANCH="release/${PADDLEX_SERIES}"
+            echo "Installing PaddleX from branch: ${PADDLEX_BRANCH}"
+            python -m pip install -e ".[all]" "paddlex@git+https://github.com/PaddlePaddle/PaddleX.git@${PADDLEX_BRANCH}"
+            python -c "import paddlex; print(f\"Installed paddlex version: {paddlex.__version__}\")"
+            python -m pytest --verbose tests/
+            '
+
+  # Aggregator: produces a single check named `test-pr-gpu` so branch
+  # protection (which requires the literal context `test-pr-gpu`) is satisfied
+  # even when the heavy GPU job is skipped (e.g. docs-only changes). Without
+  # this, a SKIPPED conclusion on the GPU job leaves the required check
+  # unsatisfied and blocks merge.
+  test-pr-gpu:
+    runs-on: ubuntu-latest
+    needs: [detect-changes, test-pr-gpu-impl]
+    if: always()
+    steps:
+      - name: Verify required jobs
+        run: |
+          if [ "${{ needs.detect-changes.result }}" != "success" ]; then
+            echo "detect-changes did not succeed: ${{ needs.detect-changes.result }}"
+            exit 1
+          fi
+          if [ "${{ needs.detect-changes.outputs.docs_only }}" = "true" ]; then
+            echo "Docs-only change; treating GPU tests as not required."
+            exit 0
+          fi
+          if [ "${{ needs.test-pr-gpu-impl.result }}" != "success" ]; then
+            echo "test-pr-gpu-impl concluded with: ${{ needs.test-pr-gpu-impl.result }}"
+            exit 1
+          fi
+          echo "GPU tests passed."

.github/workflows/tests.yml

@@ -0,0 +1,108 @@
+name: PaddleOCR PR Tests
+
+on:
+  push:
+    branches: ["main", "release/*"]
+  pull_request:
+    branches: ["main", "release/*"]
+
+permissions:
+  contents: read
+
+jobs:
+  detect-changes:
+    runs-on: ubuntu-latest
+    outputs:
+      docs_only: ${{ steps.detect.outputs.docs_only }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - id: detect
+        uses: ./.github/actions/detect-docs-only
+
+  test-pr-python:
+    runs-on: ubuntu-latest
+    needs: detect-changes
+    if: needs.detect-changes.outputs.docs_only != 'true'
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.13"]
+
+    steps:
+    - uses: actions/checkout@v6
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v6
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Cache dependencies
+      uses: actions/cache@v5
+      with:
+        path: |
+          ~/.cache/pip
+          ~/.local/lib/python${{ matrix.python-version }}/site-packages
+          ~/.paddleocr/
+        key: ${{ runner.os }}-dependencies-${{ matrix.python-version }}-${{ hashFiles('**/requirements.txt', 'pyproject.toml') }}
+        restore-keys: |
+          ${{ runner.os }}-dependencies-
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install pytest
+        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+        # On py3.8 several paddlex transitive deps require py3.9+, so only
+        # paddleocr[doc2md] is installable. See installation.md for the
+        # supported extras-by-Python-version matrix.
+        if [[ "${{ matrix.python-version }}" == "3.8" ]]; then
+          python -m pip install paddlepaddle==3.0.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
+          PADDLEOCR_EXTRAS="[doc2md]"
+        else
+          python -m pip install paddlepaddle==3.1.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
+          PADDLEOCR_EXTRAS="[all]"
+        fi
+        PADDLEX_SERIES=$(grep -oE 'paddlex\[[^]]+\]>=[0-9]+\.[0-9]+' pyproject.toml | head -1 | grep -oE '[0-9]+\.[0-9]+')
+        if [ -z "$PADDLEX_SERIES" ]; then
+          echo "Failed to determine PaddleX version requirement from pyproject.toml" >&2
+          exit 1
+        fi
+
+        python -m pip install "paddlex>=3.7.0,<3.8.0"
+        PADDLEX_BRANCH="release/${PADDLEX_SERIES}"
+        echo "Installing PaddleX from branch: ${PADDLEX_BRANCH}"
+        python -m pip install -e ".${PADDLEOCR_EXTRAS}" "paddlex@git+https://github.com/PaddlePaddle/PaddleX.git@${PADDLEX_BRANCH}"
+        python -c "import paddlex; print(f'Installed paddlex version: {paddlex.__version__}')"
+    - name: Test with pytest
+      run: |
+        # Skip py38_incompatible tests on py3.8.
+        if [[ "${{ matrix.python-version }}" == "3.8" ]]; then
+          pytest --verbose tests/ -m "not resource_intensive and not py38_incompatible"
+        else
+          pytest --verbose tests/
+        fi
+
+  # Aggregator: produces a single check named `test-pr` so branch protection
+  # (which requires the literal context `test-pr`) is satisfied. Without this,
+  # the matrix above only emits `test-pr (3.x)` checks and the required
+  # `test-pr` context never reports.
+  test-pr:
+    runs-on: ubuntu-latest
+    needs: [detect-changes, test-pr-python]
+    if: always()
+    steps:
+      - name: Verify required jobs
+        run: |
+          if [ "${{ needs.detect-changes.result }}" != "success" ]; then
+            echo "detect-changes did not succeed: ${{ needs.detect-changes.result }}"
+            exit 1
+          fi
+          if [ "${{ needs.detect-changes.outputs.docs_only }}" = "true" ]; then
+            echo "Docs-only change; skipping python tests."
+            exit 0
+          fi
+          if [ "${{ needs.test-pr-python.result }}" != "success" ]; then
+            echo "test-pr-python concluded with: ${{ needs.test-pr-python.result }}"
+            exit 1
+          fi
+          echo "All python matrix variants passed."