fix: use dorny/paths-filter so required checks pass on docs-only PRs (#427)

* fix: use dorny/paths-filter so required checks pass on docs-only PRs

Replace workflow-level `paths-ignore` with job-level path filtering
using `dorny/paths-filter`. When a PR only touches docs, markdown, or
npm files the work jobs are skipped — but the workflow still triggers,
so required status checks (fmt:required, lint:required, test:required)
report as skipped instead of missing entirely.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: add comment explaining why test job checks discover's result

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: lwshang

.github/workflows/checks.yml

@@ -4,25 +4,33 @@ on:
   push:
     branches:
       - main
-    paths-ignore:
-      # NOTE: docs/reference/cli.md is auto-generated and ideally should trigger
-      # the cli-ref check when manually edited. However, GitHub Actions does not
-      # support combining paths-ignore with negation patterns, so we accept the
-      # tradeoff: manual edits to that file won't be caught in isolation, but
-      # will be caught the next time any Rust source is changed and the checks run.
-      - "**.md"
-      - "docs-site/**"
-      - "npm/**"
   pull_request:
-    paths-ignore:
-      # See push paths-ignore NOTE above for the tradeoff explanation.
-      - "**.md"
-      - "docs-site/**"
-      - "npm/**"
 
 jobs:
+  changes:
+    runs-on: ubuntu-latest
+    outputs:
+      src: ${{ steps.filter.outputs.src }}
+    permissions:
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+      - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        id: filter
+        with:
+          # 'src' is true when any changed file matches a positive pattern
+          # and does not match a negative pattern (! prefix).
+          filters: |
+            src:
+              - '**'
+              - '!**.md'
+              - '!docs-site/**'
+              - '!npm/**'
+
   compile:
     name: compile:required
+    needs: changes
+    if: needs.changes.outputs.src == 'true'
     runs-on: ubuntu-latest
 
     steps:
@@ -42,7 +50,8 @@ jobs:
 
   lint:
     name: lint:required
-    needs: compile # Run after compilation to use the cache
+    needs: [changes, compile]
+    if: needs.changes.outputs.src == 'true'
     runs-on: ubuntu-latest
 
     steps:
@@ -62,7 +71,8 @@ jobs:
 
   format:
     name: fmt:required
-    needs: compile
+    needs: [changes, compile]
+    if: needs.changes.outputs.src == 'true'
     runs-on: ubuntu-latest
 
     steps:
@@ -80,6 +90,8 @@ jobs:
 
   toml-format:
     name: toml-fmt:required
+    needs: changes
+    if: needs.changes.outputs.src == 'true'
     runs-on: ubuntu-latest
 
     steps:
@@ -106,7 +118,8 @@ jobs:
     # generate the CLI reference file and check if it is up to date
     #
     name: cli-ref:required
-    needs: compile
+    needs: [changes, compile]
+    if: needs.changes.outputs.src == 'true'
     runs-on: ubuntu-latest
 
     steps:
@@ -140,7 +153,8 @@ jobs:
     # generate config schemas and check if they are up to date
     #
     name: icp-yaml-schema:required
-    needs: compile
+    needs: [changes, compile]
+    if: needs.changes.outputs.src == 'true'
     runs-on: ubuntu-latest
 
     steps:

.github/workflows/test.yml

@@ -4,17 +4,7 @@ on:
   push:
     branches:
       - main
-    paths-ignore:
-      - "**.md"
-      - "docs/**"
-      - "docs-site/**"
-      - "npm/**"
   pull_request:
-    paths-ignore:
-      - "**.md"
-      - "docs/**"
-      - "docs-site/**"
-      - "npm/**"
 
 env:
   # When getting Rust dependencies, retry on network error:
@@ -31,7 +21,30 @@ defaults:
     shell: bash
 
 jobs:
+  changes:
+    runs-on: ubuntu-latest
+    outputs:
+      src: ${{ steps.filter.outputs.src }}
+    permissions:
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+      - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        id: filter
+        with:
+          # 'src' is true when any changed file matches a positive pattern
+          # and does not match a negative pattern (! prefix).
+          filters: |
+            src:
+              - '**'
+              - '!**.md'
+              - '!docs/**'
+              - '!docs-site/**'
+              - '!npm/**'
+
   discover:
+    needs: changes
+    if: needs.changes.outputs.src == 'true'
     runs-on: ubuntu-latest
     outputs:
       matrix: ${{ steps.set-matrix.outputs.matrix }}
@@ -42,6 +55,8 @@ jobs:
 
   unit-tests:
     name: Unit tests on ${{ matrix.os }}
+    needs: changes
+    if: needs.changes.outputs.src == 'true'
     runs-on: ${{ matrix.os }}
 
     strategy:
@@ -71,6 +86,9 @@ jobs:
     name: ${{ matrix.test }} on ${{ matrix.os }}
     # Wait until unit tests have run so we can reuse the cache
     needs: [discover, unit-tests]
+    # Check discover's result (not changes.outputs.src) because this job
+    # needs discover's matrix output, which is only available when it ran.
+    if: needs.discover.result == 'success'
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
@@ -144,10 +162,13 @@ jobs:
 
   aggregate:
     name: test:required
-    if: ${{ always() }}
+    if: always() && needs.changes.outputs.src == 'true'
     runs-on: ubuntu-latest
-    needs: [unit-tests, test]
+    needs: [changes, unit-tests, test]
     steps:
-      - name: check result
-        if: ${{ needs.unit-tests.result != 'success' || needs.test.result != 'success' }}
+      - name: check unit-tests result
+        if: ${{ needs.unit-tests.result != 'success' }}
+        run: exit 1
+      - name: check test result
+        if: ${{ needs.test.result != 'success' }}
         run: exit 1

.github/workflows/validate-examples.yml

@@ -4,20 +4,7 @@ on:
   push:
     branches:
       - main
-    paths-ignore:
-      # NOTE: all docs/ markdown files are covered by "**.md" above. The only
-      # docs/ files that still trigger this workflow are docs/schemas/*.json —
-      # intentionally, since this workflow validates project manifests against
-      # those schemas.
-      - "**.md"
-      - "docs-site/**"
-      - "npm/**"
   pull_request:
-    paths-ignore:
-      # See push paths-ignore NOTE above.
-      - "**.md"
-      - "docs-site/**"
-      - "npm/**"
 
 env:
   # When getting Rust dependencies, retry on network error:
@@ -26,8 +13,30 @@ env:
   CURL_HOME: .
 
 jobs:
+  changes:
+    runs-on: ubuntu-latest
+    outputs:
+      src: ${{ steps.filter.outputs.src }}
+    permissions:
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+      - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        id: filter
+        with:
+          # 'src' is true when any changed file matches a positive pattern
+          # and does not match a negative pattern (! prefix).
+          filters: |
+            src:
+              - '**'
+              - '!**.md'
+              - '!docs-site/**'
+              - '!npm/**'
+
   validate-examples:
     name: Validate Examples on ${{ matrix.os }}
+    needs: changes
+    if: needs.changes.outputs.src == 'true'
     runs-on: ${{ matrix.os }}
 
     strategy:
@@ -54,10 +63,10 @@ jobs:
 
   aggregate:
     name: validate-examples:required
-    if: ${{ always() }}
+    if: always() && needs.changes.outputs.src == 'true'
     runs-on: ubuntu-latest
-    needs: [validate-examples]
+    needs: [changes, validate-examples]
     steps:
-      - name: check result
+      - name: check validate-examples result
         if: ${{ needs.validate-examples.result != 'success' }}
         run: exit 1