ci: skip build steps for docs-only pull requests

.github/workflows/ci-full.yml

@@ -12,9 +12,27 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  changes:
+    name: changes
+    runs-on: ubuntu-24.04
+    outputs:
+      code: ${{ steps.detect.outputs.code }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      # Docs-only pull requests skip the work below; see
+      # scripts/ci_changes.py. Jobs that branch protection requires keep
+      # running and skip only their steps, so their check names are still
+      # reported.
+      - id: detect
+        run: python3 scripts/ci_changes.py
+
   build-and-test:
     name: "${{ matrix.compiler }} C++${{ matrix.std }}"
     runs-on: ${{ matrix.os }}
+    needs: changes
 
     strategy:
       fail-fast: false
@@ -89,11 +107,12 @@ jobs:
 
     steps:
       - name: Checkout repository
+        if: needs.changes.outputs.code == 'true'
         uses: actions/checkout@v4
 
       # Linux: install compilers
       - name: Setup Compiler (Linux)
-        if: runner.os == 'Linux'
+        if: needs.changes.outputs.code == 'true' && runner.os == 'Linux'
         shell: bash
         run: |
           ver=$(echo "${{ matrix.compiler }}" | cut -d'-' -f2)
@@ -116,7 +135,7 @@ jobs:
 
       # Windows: detect MSVC vs clang-cl
       - name: Configure CMake (Windows)
-        if: runner.os == 'Windows'
+        if: needs.changes.outputs.code == 'true' && runner.os == 'Windows'
         run: |
           # windows-latest moved to windows-2025-vs2026, which ships only
           # Visual Studio 2026 (generator "Visual Studio 18 2026"); the old
@@ -142,7 +161,7 @@ jobs:
 
       # Linux: configure
       - name: Configure CMake (Linux)
-        if: runner.os == 'Linux'
+        if: needs.changes.outputs.code == 'true' && runner.os == 'Linux'
         run: |
           cmake -S . -B build \
             -DCMAKE_CXX_STANDARD=${{ matrix.std }} \
@@ -152,12 +171,13 @@ jobs:
             -DPTN_SKIP_COMPILER_CHECK=ON
 
       - name: Build
+        if: needs.changes.outputs.code == 'true'
         run: cmake --build build --config Release --parallel
 
       # CMake/MSBuild initializes the compiler environment for builds,
       # but compile-fail tests invoke cl.exe directly from CTest.
       - name: Set MSVC include paths for compile-fail tests
-        if: matrix.compiler == 'msvc'
+        if: needs.changes.outputs.code == 'true' && matrix.compiler == 'msvc'
         shell: pwsh
         run: |
           $vswhere = "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe"
@@ -171,6 +191,7 @@ jobs:
           $include | Where-Object { $_ -match '^INCLUDE=' } | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
 
       - name: Run tests
+        if: needs.changes.outputs.code == 'true'
         run: ctest --test-dir build -C Release --output-on-failure
 
       - name: Upload test log (on failure)

.github/workflows/ci-pr.yml

@@ -10,21 +10,43 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  changes:
+    name: changes
+    runs-on: ubuntu-24.04
+    outputs:
+      code: ${{ steps.detect.outputs.code }}
+      perf: ${{ steps.detect.outputs.perf }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      # Docs-only pull requests skip the work below; see
+      # scripts/ci_changes.py. Jobs that branch protection requires keep
+      # running and skip only their steps, so their check names are still
+      # reported.
+      - id: detect
+        run: python3 scripts/ci_changes.py
+
   pr-test:
     name: Ubuntu / Clang / Debug
     runs-on: ubuntu-24.04
+    needs: changes
 
     steps:
       - uses: actions/checkout@v4
+        if: needs.changes.outputs.code == 'true'
 
       - name: Set up Clang
+        if: needs.changes.outputs.code == 'true'
         run: |
           sudo apt-get update
           sudo apt-get install -y clang
           echo "CXX=clang++" >> $GITHUB_ENV
           clang++ --version
 
       - name: Configure (Debug build)
+        if: needs.changes.outputs.code == 'true'
         run: |
           cmake -S . -B build \
             -DCMAKE_BUILD_TYPE=Debug \
@@ -34,9 +56,11 @@ jobs:
             -DPTN_SKIP_COMPILER_CHECK=ON
 
       - name: Build
+        if: needs.changes.outputs.code == 'true'
         run: cmake --build build --parallel
 
       - name: Run Tests
+        if: needs.changes.outputs.code == 'true'
         run: ctest --test-dir build --output-on-failure
 
       - name: Upload test log (on failure)
@@ -49,18 +73,22 @@ jobs:
   ct-bench-build:
     name: Ubuntu / Clang / Compile-Time Bench Build
     runs-on: ubuntu-24.04
+    needs: changes
 
     steps:
       - uses: actions/checkout@v4
+        if: needs.changes.outputs.code == 'true'
 
       - name: Set up Clang
+        if: needs.changes.outputs.code == 'true'
         run: |
           sudo apt-get update
           sudo apt-get install -y clang
           echo "CXX=clang++" >> $GITHUB_ENV
           clang++ --version
 
       - name: Configure compile-time benchmarks
+        if: needs.changes.outputs.code == 'true'
         run: |
           cmake -S . -B build_ct \
             -DCMAKE_BUILD_TYPE=Release \
@@ -70,16 +98,19 @@ jobs:
             -DPTN_SKIP_COMPILER_CHECK=ON
 
       - name: Build compile-time benchmarks
+        if: needs.changes.outputs.code == 'true'
         run: cmake --build build_ct --target ptn_bench_ct --parallel
 
       - name: Report build time
-        if: always()
+        if: needs.changes.outputs.code == 'true' && always()
         run: |
           echo "Compile-time benchmarks built successfully."
 
   benchmark:
     name: Benchmark (informational)
     runs-on: ubuntu-24.04
+    if: needs.changes.outputs.perf == 'true'
+    needs: changes
     # Informational only — does not block PR merge.
     # Benchmark failures surface as artifacts for review, not as red X.
     continue-on-error: true

.github/workflows/ci.yml

@@ -13,21 +13,42 @@ on:
     branches: [main]
     # NOTE: no paths-ignore here on purpose. Branch protection
     # requires the build-and-test/coverage checks from this
-    # workflow; skipping docs-only PRs would leave those checks
-    # unreported and block the merge (see PR #45).
+    # workflow; skipping the whole workflow for docs-only PRs would
+    # leave those checks unreported and block the merge (see PR #45).
+    # Instead the jobs run and the `changes` job turns their steps off.
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
+  changes:
+    name: changes
+    runs-on: ubuntu-24.04
+    outputs:
+      code: ${{ steps.detect.outputs.code }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      # Docs-only pull requests skip the work below; see
+      # scripts/ci_changes.py. Jobs that branch protection requires keep
+      # running and skip only their steps, so their check names are still
+      # reported.
+      - id: detect
+        run: python3 scripts/ci_changes.py
+
   build-and-test:
     runs-on: ubuntu-24.04
+    needs: changes
 
     steps:
       - uses: actions/checkout@v4
+        if: needs.changes.outputs.code == 'true'
 
       - name: Configure CMake
+        if: needs.changes.outputs.code == 'true'
         run: |
           cmake -S . -B build \
             -DCMAKE_BUILD_TYPE=Release \
@@ -36,9 +57,11 @@ jobs:
             -DPTN_SKIP_COMPILER_CHECK=ON
 
       - name: Build
+        if: needs.changes.outputs.code == 'true'
         run: cmake --build build --parallel
 
       - name: Run Tests
+        if: needs.changes.outputs.code == 'true'
         run: ctest --test-dir build --output-on-failure
 
       - name: Upload test log (on failure)
@@ -49,19 +72,22 @@ jobs:
           path: build/Testing/Temporary/LastTest.log
 
   coverage:
-    needs: build-and-test
     runs-on: ubuntu-24.04
+    needs: [changes, build-and-test]
     steps:
       - uses: actions/checkout@v4
+        if: needs.changes.outputs.code == 'true'
 
       - name: Install LLVM tools
+        if: needs.changes.outputs.code == 'true'
         run: |
           wget -qO- https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
           sudo add-apt-repository -y 'deb http://apt.llvm.org/jammy/ llvm-toolchain-jammy-18 main'
           sudo apt-get update -qq
           sudo apt-get install -y -qq llvm-18 clang-18
 
       - name: Configure (Clang + source-based coverage)
+        if: needs.changes.outputs.code == 'true'
         run: |
           cmake -S . -B build \
             -DCMAKE_BUILD_TYPE=Debug \
@@ -74,9 +100,11 @@ jobs:
             -DPTN_SKIP_COMPILER_CHECK=ON
 
       - name: Build
+        if: needs.changes.outputs.code == 'true'
         run: cmake --build build --parallel
 
       - name: Run Tests
+        if: needs.changes.outputs.code == 'true'
         env:
           # Give each test process its own raw profile file.
           # %p = PID, %m = binary module name → avoids overwrites across
@@ -87,6 +115,7 @@ jobs:
           ctest --test-dir build --output-on-failure
 
       - name: Capture coverage
+        if: needs.changes.outputs.code == 'true'
         run: |
           # Merge raw profiles from all test processes.
           find build/profile -name '*.profraw' > profraw_list.txt
@@ -112,6 +141,7 @@ jobs:
             build/tests/ptn_tests
 
       - name: Upload to Codecov
+        if: needs.changes.outputs.code == 'true'
         uses: codecov/codecov-action@v5
         with:
           token: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/clang-format-check.yml

@@ -14,19 +14,40 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  changes:
+    name: changes
+    runs-on: ubuntu-24.04
+    outputs:
+      code: ${{ steps.detect.outputs.code }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      # Docs-only pull requests skip the work below; see
+      # scripts/ci_changes.py. Jobs that branch protection requires keep
+      # running and skip only their steps, so their check names are still
+      # reported.
+      - id: detect
+        run: python3 scripts/ci_changes.py
+
   clang-format:
     runs-on: ubuntu-24.04
+    needs: changes
 
     steps:
       - uses: actions/checkout@v4
+        if: needs.changes.outputs.code == 'true'
         with:
           fetch-depth: 0
 
       - uses: actions/setup-python@v5
+        if: needs.changes.outputs.code == 'true'
         with:
           python-version: "3.12"
 
       - name: Check formatting of changed C/C++ files
+        if: needs.changes.outputs.code == 'true'
         shell: bash
         run: |
           if [ "${{ github.event_name }}" = "pull_request" ]; then

.github/workflows/clang-tidy.yml

@@ -14,8 +14,27 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  changes:
+    name: changes
+    runs-on: ubuntu-24.04
+    outputs:
+      code: ${{ steps.detect.outputs.code }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      # Docs-only pull requests skip the work below; see
+      # scripts/ci_changes.py. Jobs that branch protection requires keep
+      # running and skip only their steps, so their check names are still
+      # reported.
+      - id: detect
+        run: python3 scripts/ci_changes.py
+
   clang-tidy:
     runs-on: ubuntu-24.04
+    if: needs.changes.outputs.code == 'true'
+    needs: changes
 
     steps:
       - uses: actions/checkout@v4

.github/workflows/fuzz.yml

@@ -17,8 +17,27 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  changes:
+    name: changes
+    runs-on: ubuntu-24.04
+    outputs:
+      code: ${{ steps.detect.outputs.code }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      # Docs-only pull requests skip the work below; see
+      # scripts/ci_changes.py. Jobs that branch protection requires keep
+      # running and skip only their steps, so their check names are still
+      # reported.
+      - id: detect
+        run: python3 scripts/ci_changes.py
+
   fuzz:
     runs-on: ubuntu-24.04
+    if: needs.changes.outputs.code == 'true'
+    needs: changes
 
     steps:
       - uses: actions/checkout@v4