ci: skip builds for documentation-only changes

Author: PastaPastaPasta

.github/workflows/build.yml

@@ -8,6 +8,7 @@ permissions:
   actions: read
   contents: read
   packages: write
+  pull-requests: read
 
 concurrency:
   group: |
@@ -25,6 +26,7 @@ jobs:
     runs-on: ${{ vars.RUNNER_CHECK_SKIP || 'ubuntu-24.04-arm' }}
     outputs:
       skip: ${{ steps.skip-check.outputs.skip }}
+      run-build-tests: ${{ steps.classify-changes.outputs.run-build-tests }}
       runner-amd64: ${{ steps.select-runner.outputs.runner_amd64 }}
       runner-arm64: ${{ steps.select-runner.outputs.runner_arm64 }}
       use-blacksmith: ${{ steps.select-runner.outputs.use_blacksmith }}
@@ -39,18 +41,87 @@ jobs:
         run: |
           if [[ "${{ github.event_name }}" == "push" && "${{ vars.SKIP_ON_PUSH }}" != "" ]]; then
             echo "Skipping build on push due to SKIP_ON_PUSH environment variable"
-            echo "skip=true" >> $GITHUB_OUTPUT
+            echo "skip=true" >> "$GITHUB_OUTPUT"
           elif [[ "${{ github.event_name }}" == "pull_request_target" && "${{ vars.SKIP_ON_PR }}" != "" ]]; then
             echo "Skipping build on pull request due to SKIP_ON_PR environment variable"
-            echo "skip=true" >> $GITHUB_OUTPUT
+            echo "skip=true" >> "$GITHUB_OUTPUT"
           else
-            echo "skip=false" >> $GITHUB_OUTPUT
+            echo "skip=false" >> "$GITHUB_OUTPUT"
           fi
 
       - name: Checkout code
         if: ${{ steps.skip-check.outputs.skip == 'false' }}
         uses: actions/checkout@v6
 
+      - name: Collect changed paths
+        id: changed-paths
+        if: ${{ steps.skip-check.outputs.skip == 'false' }}
+        uses: actions/github-script@v8
+        env:
+          CHANGED_PATHS_FILE: ${{ runner.temp }}/changed-paths.json
+        with:
+          script: |
+            const fs = require('fs');
+            let complete = true;
+            let files = [];
+
+            try {
+              if (context.eventName === 'pull_request_target') {
+                files = await github.paginate(github.rest.pulls.listFiles, {
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  pull_number: context.payload.pull_request.number,
+                  per_page: 100,
+                });
+                if (files.length >= 3000) {
+                  complete = false;
+                  core.warning('Pull request file list reached the GitHub API limit');
+                }
+              } else if (context.eventName === 'push') {
+                const before = context.payload.before;
+                const after = context.payload.after;
+                if (context.ref.startsWith('refs/tags/') || !before || /^0+$/.test(before)) {
+                  complete = false;
+                } else {
+                  const comparison = await github.rest.repos.compareCommitsWithBasehead({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    basehead: `${before}...${after}`,
+                  });
+                  files = comparison.data.files || [];
+                  if (files.length >= 300) {
+                    complete = false;
+                    core.warning('Push file list reached the GitHub API limit');
+                  }
+                }
+              } else {
+                complete = false;
+              }
+            } catch (error) {
+              complete = false;
+              core.warning(`Unable to collect a complete changed path list: ${error.message}`);
+            }
+
+            const paths = [...new Set(files.flatMap(file =>
+              [file.filename, file.previous_filename].filter(Boolean)
+            ))].sort();
+            fs.writeFileSync(process.env.CHANGED_PATHS_FILE, JSON.stringify(paths));
+            core.setOutput('complete', complete.toString());
+
+      - name: Classify changed paths
+        id: classify-changes
+        if: ${{ steps.skip-check.outputs.skip == 'false' }}
+        env:
+          CHANGED_PATHS_COMPLETE: ${{ steps.changed-paths.outputs.complete }}
+          CHANGED_PATHS_FILE: ${{ runner.temp }}/changed-paths.json
+        run: |
+          if ! python3 .github/workflows/classify_ci_changes.py \
+            --complete "$CHANGED_PATHS_COMPLETE" "$CHANGED_PATHS_FILE"; then
+            echo "Path classification failed; running the full build and test matrix"
+            echo "run-build-tests=true" >> "$GITHUB_OUTPUT"
+            echo "decision-reason=path classification failed" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Select runners
         id: select-runner
         if: ${{ steps.skip-check.outputs.skip == 'false' }}
@@ -65,7 +136,9 @@ jobs:
 
       - name: Get base image digest
         id: base-image
-        if: ${{ steps.skip-check.outputs.skip == 'false' }}
+        if: |
+          steps.skip-check.outputs.skip == 'false' &&
+          steps.classify-changes.outputs.run-build-tests == 'true'
         run: |
           # Fetch the canonical manifest digest for ubuntu:noble so the
           # depends cache key changes when Canonical pushes base image
@@ -86,15 +159,19 @@ jobs:
   cache-sources:
     name: Cache depends sources
     needs: [check-skip]
-    if: ${{ needs.check-skip.outputs.skip == 'false' }}
+    if: |
+      needs.check-skip.outputs.skip == 'false' &&
+      needs.check-skip.outputs.run-build-tests == 'true'
     uses: ./.github/workflows/cache-depends-sources.yml
     with:
       runs-on: ${{ needs.check-skip.outputs['runner-arm64'] }}
 
   container:
     name: Build container
     needs: [check-skip]
-    if: ${{ needs.check-skip.outputs.skip == 'false' }}
+    if: |
+      needs.check-skip.outputs.skip == 'false' &&
+      needs.check-skip.outputs.run-build-tests == 'true'
     uses: ./.github/workflows/build-container.yml
     with:
       context: ./contrib/containers/ci

.github/workflows/classify_ci_changes.py

@@ -0,0 +1,143 @@
+# Copyright (c) 2026 The Dash Core developers
+# Distributed under the MIT software license, see the accompanying
+# file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+import argparse
+import json
+import os
+from pathlib import PurePosixPath
+from typing import Dict, List, Optional, Sequence
+
+
+EXCLUDED_EXACT_PATHS = {
+    "COPYING",
+    "doc/.gitignore",
+}
+EXCLUDED_PREFIXES = (
+    ".github/ISSUE_TEMPLATE/",
+    ".github/PULL_REQUEST_TEMPLATE/",
+)
+EXCLUDED_DOC_SUFFIXES = {".1", ".5", ".8", ".png", ".svg", ".txt"}
+
+
+def is_excluded_path(path: str) -> bool:
+    if not path:
+        return False
+    if path in EXCLUDED_EXACT_PATHS or path.startswith(EXCLUDED_PREFIXES):
+        return True
+
+    suffix = PurePosixPath(path).suffix
+    if suffix == ".md":
+        return True
+    return path.startswith("doc/") and suffix in EXCLUDED_DOC_SUFFIXES
+
+
+def classify_changes(paths: Sequence[str], complete: bool) -> Dict[str, object]:
+    unique_paths = sorted(set(paths))
+    if not complete:
+        return {
+            "run_build_tests": True,
+            "reason": "changed path list is incomplete",
+            "paths": unique_paths,
+            "triggering_paths": [],
+        }
+    if not unique_paths:
+        return {
+            "run_build_tests": True,
+            "reason": "no changed paths were reported",
+            "paths": unique_paths,
+            "triggering_paths": [],
+        }
+
+    triggering_paths = [path for path in unique_paths if not is_excluded_path(path)]
+    if triggering_paths:
+        reason = "build-relevant or unclassified paths changed"
+    else:
+        reason = "all changed paths are in CI exclusion zones"
+    return {
+        "run_build_tests": bool(triggering_paths),
+        "reason": reason,
+        "paths": unique_paths,
+        "triggering_paths": triggering_paths,
+    }
+
+
+def load_paths(path: str) -> List[str]:
+    with open(path, "r", encoding="utf-8") as file:
+        paths = json.load(file)
+    if not isinstance(paths, list) or not all(isinstance(item, str) for item in paths):
+        raise ValueError("changed paths must be a JSON array of strings")
+    return paths
+
+
+def write_github_output(path: Optional[str], result: Dict[str, object]) -> None:
+    if not path:
+        return
+    with open(path, "a", encoding="utf-8") as file:
+        file.write(
+            "run-build-tests={}\n".format(
+                "true" if result["run_build_tests"] else "false"
+            )
+        )
+        file.write("decision-reason={}\n".format(result["reason"]))
+
+
+def write_step_summary(
+    path: Optional[str], result: Dict[str, object], complete: bool
+) -> None:
+    if not path:
+        return
+
+    triggering_paths = result["triggering_paths"]
+    with open(path, "a", encoding="utf-8") as file:
+        file.write("### Build and test path classification\n")
+        file.write(
+            "- Changed path list complete: {}\n".format(
+                "yes" if complete else "no"
+            )
+        )
+        file.write("- Changed paths examined: {}\n".format(len(result["paths"])))
+        file.write(
+            "- Full build and test matrix: {}\n".format(
+                "required" if result["run_build_tests"] else "skipped"
+            )
+        )
+        file.write("- Decision: `{}`\n".format(result["reason"]))
+        if triggering_paths:
+            file.write("- Triggering paths (up to 20):\n")
+            for changed_path in triggering_paths[:20]:
+                file.write(
+                    "  - `{}`\n".format(json.dumps(changed_path, ensure_ascii=True))
+                )
+
+
+def parse_args(argv: Sequence[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Classify changed paths for Dash CI.")
+    parser.add_argument("paths_json", help="JSON file containing changed paths")
+    parser.add_argument(
+        "--complete",
+        choices=("true", "false"),
+        required=True,
+        help="Whether the changed path list is known to be complete",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: Sequence[str]) -> int:
+    args = parse_args(argv)
+    complete = args.complete == "true"
+    result = classify_changes(load_paths(args.paths_json), complete)
+    write_github_output(os.environ.get("GITHUB_OUTPUT"), result)
+    write_step_summary(os.environ.get("GITHUB_STEP_SUMMARY"), result, complete)
+    print(
+        "run-build-tests={} ({})".format(
+            "true" if result["run_build_tests"] else "false", result["reason"]
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    import sys
+
+    sys.exit(main(sys.argv[1:]))

.github/workflows/test_classify_ci_changes.py

@@ -0,0 +1,100 @@
+import importlib.util
+import json
+import pathlib
+import tempfile
+import unittest
+
+
+MODULE_PATH = pathlib.Path(__file__).with_name("classify_ci_changes.py")
+SPEC = importlib.util.spec_from_file_location("classify_ci_changes", MODULE_PATH)
+MODULE = importlib.util.module_from_spec(SPEC)
+assert SPEC.loader is not None
+SPEC.loader.exec_module(MODULE)
+
+
+class ClassifyCIChangesTest(unittest.TestCase):
+    def test_markdown_files_are_excluded_at_any_depth(self):
+        for path in ("README.md", "doc/release-notes-1234.md", "depends/README.md"):
+            with self.subTest(path=path):
+                self.assertTrue(MODULE.is_excluded_path(path))
+
+    def test_static_documentation_files_are_excluded(self):
+        for path in (
+            "doc/assets/diagram.png",
+            "doc/assets/diagram.svg",
+            "doc/man/dashd.1",
+            "doc/notes.txt",
+        ):
+            with self.subTest(path=path):
+                self.assertTrue(MODULE.is_excluded_path(path))
+
+    def test_documentation_build_inputs_are_not_excluded(self):
+        for path in ("doc/Doxyfile.in", "doc/man/Makefile.am"):
+            with self.subTest(path=path):
+                self.assertFalse(MODULE.is_excluded_path(path))
+
+    def test_repository_templates_and_license_are_excluded(self):
+        for path in (
+            ".github/ISSUE_TEMPLATE/config.yml",
+            ".github/PULL_REQUEST_TEMPLATE/release.md",
+            ".github/PULL_REQUEST_TEMPLATE.md",
+            "COPYING",
+        ):
+            with self.subTest(path=path):
+                self.assertTrue(MODULE.is_excluded_path(path))
+
+    def test_build_relevant_and_unknown_paths_require_tests(self):
+        for path in (
+            "src/net.cpp",
+            "test/functional/p2p_invalid_messages.py",
+            "depends/packages/boost.mk",
+            "ci/dash/matrix.sh",
+            ".github/workflows/build.yml",
+            "configure.ac",
+            "new-area/README.txt",
+        ):
+            with self.subTest(path=path):
+                self.assertFalse(MODULE.is_excluded_path(path))
+
+    def test_only_excluded_paths_skip_builds_and_tests(self):
+        result = MODULE.classify_changes(
+            ["README.md", "doc/man/dashd.1", ".github/ISSUE_TEMPLATE/config.yml"],
+            complete=True,
+        )
+
+        self.assertFalse(result["run_build_tests"])
+        self.assertEqual(result["triggering_paths"], [])
+
+    def test_mixed_changes_require_builds_and_tests(self):
+        result = MODULE.classify_changes(
+            ["doc/release-notes-1234.md", "src/net.cpp"], complete=True
+        )
+
+        self.assertTrue(result["run_build_tests"])
+        self.assertEqual(result["triggering_paths"], ["src/net.cpp"])
+
+    def test_previous_rename_path_can_require_builds_and_tests(self):
+        result = MODULE.classify_changes(
+            ["doc/retired-code.md", "src/retired-code.cpp"], complete=True
+        )
+
+        self.assertTrue(result["run_build_tests"])
+        self.assertEqual(result["triggering_paths"], ["src/retired-code.cpp"])
+
+    def test_incomplete_or_empty_path_lists_fail_open(self):
+        for paths, complete in ((["README.md"], False), ([], True)):
+            with self.subTest(paths=paths, complete=complete):
+                result = MODULE.classify_changes(paths, complete)
+                self.assertTrue(result["run_build_tests"])
+
+    def test_load_paths_rejects_malformed_input(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = pathlib.Path(directory) / "paths.json"
+            path.write_text(json.dumps({"path": "README.md"}), encoding="utf-8")
+
+            with self.assertRaisesRegex(ValueError, "JSON array of strings"):
+                MODULE.load_paths(str(path))
+
+
+if __name__ == "__main__":
+    unittest.main()