diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e62da101..e2a28760 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -24,25 +24,34 @@ env: jobs: changes: - name: classify developer dependencies + name: classify changes permissions: contents: read pull-requests: read runs-on: ubuntu-24.04 timeout-minutes: 5 outputs: - dev: ${{ steps.classify.outputs.dev }} + dev: ${{ steps.classify-dev.outputs.dev }} + docs-only: ${{ steps.classify.outputs.docs-only }} steps: - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 with: persist-credentials: false fetch-depth: 0 - name: Compare the actual source range - id: classify + id: classify-dev env: GH_TOKEN: ${{ github.token }} run: python scripts/ci/dev_changes.py + - name: Test change classification + run: python3 -m unittest discover -s tests -p test_ci_changes.py + - name: Classify the complete PR diff + id: classify + env: + GH_TOKEN: ${{ github.token }} + run: python3 scripts/ci_changes.py + developer-tools: name: developer tools / CPU needs: changes @@ -79,6 +88,7 @@ jobs: retention-days: 14 lint: + needs: changes timeout-minutes: 15 name: lint runs-on: ubuntu-24.04 @@ -98,8 +108,15 @@ jobs: - run: uv sync --locked --extra dev --python 3.12 - run: make requirements-check - run: make ci-lint + - name: Check documentation package metadata and architecture claims + if: needs.changes.outputs.docs-only == 'true' + run: | + make package-check + make test-docs test-cpu: + needs: changes + if: needs.changes.outputs.docs-only != 'true' timeout-minutes: 30 name: tests / ${{ matrix.name }} / py${{ matrix.python }} strategy: @@ -187,6 +204,8 @@ jobs: --output-dir "${RUNNER_TEMP}/cuphoton-quickstart" test-nooa: + needs: changes + if: needs.changes.outputs.docs-only != 'true' name: xLens NOOA / ${{ matrix.name }} / py${{ matrix.python }} runs-on: ${{ matrix.runner }} timeout-minutes: 15 @@ -236,9 +255,12 @@ jobs: run: uv run --no-sync pytest -q -rs tests/xlens test-gpu: + needs: changes name: xFit, xRay and GPU quickstarts / L40G / py3.12 # Only vetted copies and maintained branches may use self-hosted GPUs. - if: github.event_name == 'push' && github.repository == 'NVIDIA/cuPhoton' + if: >- + needs.changes.outputs.docs-only != 'true' && + github.event_name == 'push' && github.repository == 'NVIDIA/cuPhoton' runs-on: linux-amd64-gpu-l40g-latest-1 timeout-minutes: 30 concurrency: @@ -589,32 +611,40 @@ jobs: retention-days: 14 coverage: + needs: changes + if: needs.changes.outputs.docs-only != 'true' name: coverage uses: ./.github/workflows/coverage.yml package: + needs: changes name: native distributions # Qualify packages once, on the same vetted source as the GPU checks. - if: github.event_name == 'push' && github.repository == 'NVIDIA/cuPhoton' + if: >- + needs.changes.outputs.docs-only != 'true' && + github.event_name == 'push' && github.repository == 'NVIDIA/cuPhoton' uses: ./.github/workflows/wheels.yml conda: + needs: changes + if: needs.changes.outputs.docs-only != 'true' name: native conda distributions uses: ./.github/workflows/conda.yml ci-required: - # PR checks do not satisfy the merge gate before package and GPU qualification. + # The vetted copy must satisfy every check selected for the complete PR diff. name: ${{ github.event_name == 'pull_request' && 'ci-pr-checks' || 'ci-required' }} needs: [changes, developer-tools, lint, test-cpu, test-nooa, test-gpu, coverage, package, conda] if: ${{ always() }} runs-on: ubuntu-24.04 timeout-minutes: 5 steps: - - name: Require every CI job to succeed + - name: Require every selected CI job to succeed env: CHANGES_RESULT: ${{ needs.changes.result }} DEV_REQUIRED: ${{ needs.changes.outputs.dev }} DEV_RESULT: ${{ needs.developer-tools.result }} + DOCS_ONLY: ${{ needs.changes.outputs.docs-only }} LINT_RESULT: ${{ needs.lint.result }} CPU_RESULT: ${{ needs.test-cpu.result }} NOOA_RESULT: ${{ needs.test-nooa.result }} @@ -629,7 +659,15 @@ jobs: true:success|false:skipped) ;; *) exit 1 ;; esac - for result in "${LINT_RESULT}" "${CPU_RESULT}" "${NOOA_RESULT}" "${COVERAGE_RESULT}" "${CONDA_RESULT}"; do + test "${LINT_RESULT}" = success || exit 1 + if [ "${DOCS_ONLY}" = true ]; then + for result in "${CPU_RESULT}" "${NOOA_RESULT}" "${GPU_RESULT}" "${COVERAGE_RESULT}" "${PACKAGE_RESULT}" "${CONDA_RESULT}"; do + test "${result}" = skipped || exit 1 + done + exit 0 + fi + test "${DOCS_ONLY}" = false || exit 1 + for result in "${CPU_RESULT}" "${NOOA_RESULT}" "${COVERAGE_RESULT}" "${CONDA_RESULT}"; do test "${result}" = success || exit 1 done if [ "${REQUIRE_FULL_CI}" = true ]; then diff --git a/.github/workflows/docs-preview.yml b/.github/workflows/docs-preview.yml index 8a31340c..e8079d34 100644 --- a/.github/workflows/docs-preview.yml +++ b/.github/workflows/docs-preview.yml @@ -7,7 +7,7 @@ run-name: docs preview PR ${{ github.event.number }} / ${{ github.sha }} on: pull_request: - branches: [main] + branches: [main, 0.1.x, 0.2.x] paths: - .github/workflows/docs-preview.yml - .github/workflows/docs.yml diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 306c6a3f..c6be0613 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -132,7 +132,7 @@ and multiprocessing workers contribute to the report. Compiled C++/CUDA code, scripts, and examples are outside this Python package measurement. No minimum percentage is enforced while establishing a baseline. -Each CI run collects coverage once in a separate Python 3.12/Linux CPU job, +Full CI collects coverage once in a separate Python 3.12/Linux CPU job, running the CPU suite and synthetic quickstarts. The regular test matrix runs without coverage instrumentation. Vetted CI pushes also run one native xDR coverage job on an L40G runner. CI requires the applicable coverage jobs @@ -197,24 +197,42 @@ these tests do not establish GPUDirect Storage coverage. ### Package and GPU CI -Pull requests first run lint, CPU, and conda checks on GitHub-hosted runners. -Native wheel builds, installed-wheel/runtime checks, and GPU CI start when -`copy-pr-bot` copies a vetted revision to +Documentation-only pull requests run lint, source-package metadata checks, +and `make test-docs`, which checks the xRay documentation and documented +GPU architectures. Changes under `docs/` also run +the user-guide build, which executes its CPU examples. These PRs skip the +full CPU matrix, coverage, native wheel builds, conda builds, and GPU jobs. +The classifier checks the complete PR diff against an explicit set of +documentation paths. Code, tests, dependencies, packaging, CI configuration, +license files, and unfamiliar paths select full CI; unavailable change +information also selects full CI. + +Developer-tool tests still run when their dependencies change, including +user-guide inputs, and their selected result is required by `ci-required`. + +Other pull requests first run lint, CPU, and conda checks on GitHub-hosted +runners. Native wheel builds, installed-wheel/runtime checks, and GPU CI +start when `copy-pr-bot` copies a vetted revision to `pull-request/` in this repository. Ready PRs from verified NVIDIA contributors with signed commits sync automatically. Draft PRs need an explicit maintainer trigger; each new external contribution revision needs maintainer approval before it can run on a GPU. +Documentation-only PRs also need a vetted copy to obtain `ci-required`. +They use the same copy process below and retain the reduced check profile. + After reviewing the current diff, a maintainer can request a bot copy with `/ok to test `. A maintainer can also push that same reviewed commit to `pull-request/` directly. Confirm that the copied SHA matches the current PR head; a passing result for an older revision does not qualify new changes. -The required `ci-required` check combines CPU, package, and GPU results for -that revision. The initial `ci-pr-checks` result does not satisfy the merge +The required `ci-required` check requires every job selected for that +revision to succeed, accepting skipped jobs only for the selected profile. +The initial `ci-pr-checks` result does not satisfy the merge gate. Pushes to `main`, `0.1.x` and `0.2.x` also run the full package and GPU -checks. +checks. The guide build is a separate, non-required check; its result is +not included in `ci-required`. Installed-wheel and runtime checks cover Python 3.12–3.14 on x86-64 and arm64. Each matrix job pulls its pinned Python image once and runs both diff --git a/MANIFEST.in b/MANIFEST.in index 4f96d850..0997032b 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -33,6 +33,7 @@ prune dev recursive-include examples *.py *.yaml recursive-include examples/distributed-pipeline *.json *.txt *.license recursive-include tests *.py +exclude tests/test_ci_changes.py recursive-include src/cuphoton/xdr/src *.cpp *.h *.sh recursive-include src/cuphoton/xfit/src *.cpp *.cu *.cuh *.h recursive-include src/cuphoton/core/src *.cpp *.cu *.h diff --git a/Makefile b/Makefile index 239c96a2..9e67a4ca 100644 --- a/Makefile +++ b/Makefile @@ -59,6 +59,11 @@ test: test-cpu: CUDA_VISIBLE_DEVICES= CUPHOTON_XREP_TORCH_DEVICE=cpu $(UV_RUN) $(CPU_EXTRAS) $(PYTEST) -rs +.PHONY: test-docs +test-docs: + $(UV_RUN) --extra dev $(PYTEST) -q tests/xray/test_docs.py \ + tests/test_xfit_build.py::test_wheel_architectures_match_documented_cubin_targets + test-cpu-coverage: $(UV_RUN) --extra dev coverage erase $(MAKE) test-cpu PYTEST="coverage run -m pytest" diff --git a/scripts/ci_changes.py b/scripts/ci_changes.py new file mode 100644 index 00000000..bb830ff2 --- /dev/null +++ b/scripts/ci_changes.py @@ -0,0 +1,126 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Select reduced CI for confirmed documentation-only pull requests.""" + +import json +import os +import re +import subprocess +from pathlib import Path, PurePosixPath + + +def is_documentation(path: str) -> bool: + if path in { + "README.md", + "CHANGELOG.md", + "CITATION.md", + "CODE_OF_CONDUCT.md", + "CONTRIBUTING.md", + "GOVERNANCE.md", + "MAINTAINERS.md", + "SECURITY.md", + "SUPPORT.md", + "docs/guide/_quarto.yml", + "docs/guide/_environment", + "docs/guide/.gitignore", + }: + return True + return path.startswith("docs/") and PurePosixPath(path).suffix in { + ".md", + ".qmd", + ".scss", + ".css", + ".png", + ".jpg", + ".jpeg", + ".svg", + ".webp", + ".gif", + ".ico", + ".bib", + } + + +def changed_paths(base: str, head: str) -> list[str]: + # Disable rename detection so moving code into docs still counts as code. + output = subprocess.check_output( + [ + "git", + "diff", + "--name-only", + "--no-renames", + "-z", + f"{base}...{head}", + "--", + ], + stderr=subprocess.PIPE, + timeout=30, + ) + return [os.fsdecode(path) for path in output.split(b"\0") if path] + + +def docs_only( + event_name: str, ref: str, sha: str, repository: str, event: dict +) -> bool: + try: + if event_name == "pull_request": + pr = event["pull_request"] + elif event_name == "push" and ( + match := re.fullmatch(r"refs/heads/pull-request/([0-9]+)", ref) + ): + pr = json.loads( + subprocess.check_output( + ["gh", "api", f"repos/{repository}/pulls/{match[1]}"], + text=True, + stderr=subprocess.PIPE, + timeout=30, + ) + ) + if pr["head"]["sha"] != sha: + return False + else: + # Maintained branches and manual qualification keep full CI. + return False + + base, head = pr["base"]["sha"], pr["head"]["sha"] + if not all( + isinstance(value, str) and re.fullmatch(r"[0-9a-f]{40}", value) + for value in (base, head) + ): + return False + # Compare the whole PR, including code changed before a docs update. + paths = changed_paths(base, head) + return bool(paths) and all(is_documentation(path) for path in paths) + except ( + KeyError, + TypeError, + ValueError, + OSError, + subprocess.SubprocessError, + ): + # Missing metadata or history must never suppress qualification. + print("Could not classify the complete PR diff; using full CI.") + return False + + +def main() -> None: + event = json.loads(Path(os.environ["GITHUB_EVENT_PATH"]).read_text()) + reduced = docs_only( + os.environ["GITHUB_EVENT_NAME"], + os.environ["GITHUB_REF"], + os.environ["GITHUB_SHA"], + os.environ["GITHUB_REPOSITORY"], + event, + ) + profile = "documentation only" if reduced else "full" + print(f"CI profile: {profile}") + with Path(os.environ["GITHUB_OUTPUT"]).open("a") as output: + output.write(f"docs-only={str(reduced).lower()}\n") + with Path(os.environ["GITHUB_STEP_SUMMARY"]).open("a") as summary: + summary.write(f"CI profile: **{profile}**.\n") + + +if __name__ == "__main__": + main() diff --git a/tests/test_ci_changes.py b/tests/test_ci_changes.py new file mode 100644 index 00000000..71bf10ca --- /dev/null +++ b/tests/test_ci_changes.py @@ -0,0 +1,237 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Exercise CI selection against complete pull-request histories.""" + +from __future__ import annotations + +import contextlib +import json +import os +import subprocess +import tempfile +import unittest +from pathlib import Path +from unittest import mock + +from scripts import ci_changes + + +class CIChangesTests(unittest.TestCase): + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.root = Path(directory.name) + self.git("init", "--initial-branch=main") + self.git("config", "user.name", "CI Tests") + self.git("config", "user.email", "tests@example.org") + self.git("config", "commit.gpgsign", "false") + self.git("config", "core.hooksPath", "/dev/null") + self.write("README.md", "Initial documentation\n") + self.write("src/example.py", "VALUE = 1\n") + self.base = self.commit() + + def git(self, *args): + return subprocess.check_output( + ["git", *args], cwd=self.root, stderr=subprocess.PIPE, text=True + ).strip() + + def write(self, name, content): + path = self.root / name + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(content) + + def commit(self): + self.git("add", "--all") + self.git("commit", "-m", "Test change") + return self.git("rev-parse", "HEAD") + + def metadata(self, head, base=None): + return { + "base": {"sha": base or self.base}, + "head": {"sha": head}, + } + + def select(self, head, *, event_name="pull_request", ref="", event=None): + if event is None: + event = {"pull_request": self.metadata(head)} + with contextlib.chdir(self.root): + return ci_changes.docs_only( + event_name, ref, head, "NVIDIA/cuPhoton", event + ) + + def test_documentation_and_guide_assets_use_reduced_ci(self): + for name in ( + "README.md", + "docs/guide/first-difference.qmd", + "docs/guide/_quarto.yml", + "docs/guide/assets/logo.png", + "docs/a name\nwith whitespace.md", + ): + self.write(name, "Updated documentation\n") + self.assertTrue(self.select(self.commit())) + + def test_unknown_and_package_inputs_require_full_ci(self): + for name in ( + "src/readme.md", + "docs/build.py", + "docs/config.yml", + "docs/requirements.txt", + "docs/guide/_extensions/filter.lua", + "pyproject.toml", + "setup.py", + "MANIFEST.in", + "Makefile", + "LICENSE", + "THIRD_PARTY_NOTICES.md", + "CITATION.cff", + "uv.lock", + ".github/workflows/ci.yml", + "examples/example.ipynb", + ): + with self.subTest(path=name): + self.assertFalse(ci_changes.is_documentation(name)) + self.write("README.md", "Updated documentation\n") + self.write("new-build-config", "Unknown input\n") + self.assertFalse(self.select(self.commit())) + + def test_docs_followup_does_not_hide_earlier_code_change(self): + self.write("src/example.py", "VALUE = 2\n") + self.commit() + self.write("README.md", "Updated documentation\n") + self.assertFalse(self.select(self.commit())) + + def test_renaming_source_into_docs_requires_full_ci(self): + self.git("mv", "src/example.py", "CONTRIBUTING.md") + self.assertFalse(self.select(self.commit())) + + def test_deleted_documentation_uses_reduced_ci(self): + (self.root / "README.md").unlink() + self.assertTrue(self.select(self.commit())) + + def test_empty_or_unavailable_diff_requires_full_ci(self): + self.assertFalse(self.select(self.base)) + self.assertFalse(self.select("0" * 40)) + + def test_maintained_pushes_and_manual_runs_keep_full_ci(self): + self.write("README.md", "Updated documentation\n") + head = self.commit() + for ref in ("main", "0.1.x", "0.2.x"): + with self.subTest(ref=ref): + self.assertFalse( + self.select( + head, event_name="push", ref=f"refs/heads/{ref}" + ) + ) + self.assertFalse(self.select(head, event_name="workflow_dispatch")) + + def test_vetted_copy_uses_verified_pr_base_and_head(self): + self.write("src/example.py", "VALUE = 2\n") + release_base = self.commit() + self.write("README.md", "Updated documentation\n") + head = self.commit() + check_output = subprocess.check_output + + def metadata_or_git(args, **kwargs): + if args[0] == "gh": + self.assertEqual(args[2], "repos/NVIDIA/cuPhoton/pulls/12") + return json.dumps(self.metadata(head, release_base)) + return check_output(args, **kwargs) + + with mock.patch.object( + ci_changes.subprocess, "check_output", side_effect=metadata_or_git + ): + self.assertTrue( + self.select( + head, event_name="push", ref="refs/heads/pull-request/12" + ) + ) + + def test_stale_vetted_copy_requires_full_ci(self): + self.write("src/example.py", "VALUE = 2\n") + copied_head = self.commit() + self.git("checkout", "-b", "replacement", self.base) + self.write("README.md", "Updated documentation\n") + current_head = self.commit() + check_output = subprocess.check_output + + def metadata_or_git(args, **kwargs): + if args[0] == "gh": + return json.dumps(self.metadata(current_head)) + return check_output(args, **kwargs) + + with mock.patch.object( + ci_changes.subprocess, "check_output", side_effect=metadata_or_git + ): + self.assertFalse( + self.select( + copied_head, + event_name="push", + ref="refs/heads/pull-request/12", + ) + ) + + def test_unavailable_pr_metadata_requires_full_ci(self): + self.write("README.md", "Updated documentation\n") + head = self.commit() + responses = ( + "{}", + "invalid JSON", + subprocess.CalledProcessError(1, ["gh", "api"]), + ) + for response in responses: + with self.subTest(response=response): + kwargs = ( + {"side_effect": response} + if isinstance(response, Exception) + else {"return_value": response} + ) + with mock.patch.object( + ci_changes.subprocess, "check_output", **kwargs + ): + self.assertFalse( + self.select( + head, + event_name="push", + ref="refs/heads/pull-request/12", + ) + ) + + def test_main_writes_selected_profile(self): + for name, expected in ( + ("README.md", "true"), + ("src/example.py", "false"), + ): + with self.subTest(path=name): + self.write(name, "Updated content\n") + head = self.commit() + event_path = self.root / ".git" / "event.json" + event_path.write_text( + json.dumps({"pull_request": self.metadata(head)}) + ) + output = self.root / ".git" / "output" + output.write_text("") + env = { + "GITHUB_EVENT_PATH": str(event_path), + "GITHUB_EVENT_NAME": "pull_request", + "GITHUB_REF": "refs/pull/12/merge", + "GITHUB_SHA": head, + "GITHUB_REPOSITORY": "NVIDIA/cuPhoton", + "GITHUB_OUTPUT": str(output), + "GITHUB_STEP_SUMMARY": str( + self.root / ".git" / "summary" + ), + } + with ( + mock.patch.dict(os.environ, env), + contextlib.chdir(self.root), + ): + ci_changes.main() + self.assertEqual( + output.read_text(), f"docs-only={expected}\n" + ) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_release.py b/tests/test_release.py index 76bb37b4..b8b63c72 100644 --- a/tests/test_release.py +++ b/tests/test_release.py @@ -10,6 +10,7 @@ import importlib.util import io import json +import os import shlex import subprocess import sys @@ -29,6 +30,58 @@ SPEC.loader.exec_module(release) +@pytest.mark.parametrize("docs_only", [False, True]) +@pytest.mark.parametrize("vetted", [False, True]) +@pytest.mark.parametrize("developer_tools", [False, True]) +def test_ci_gate_requires_every_selected_job( + docs_only, vetted, developer_tools +): + workflow = yaml.safe_load( + (SCRIPTS.parents[1] / ".github/workflows/ci.yml").read_text() + ) + script = workflow["jobs"]["ci-required"]["steps"][0]["run"] + results = { + "CHANGES_RESULT": "success", + "LINT_RESULT": "success", + "DEV_RESULT": "success" if developer_tools else "skipped", + **{ + name: "skipped" if docs_only else "success" + for name in ( + "CPU_RESULT", + "NOOA_RESULT", + "COVERAGE_RESULT", + "CONDA_RESULT", + ) + }, + **{ + name: "success" if vetted and not docs_only else "skipped" + for name in ("GPU_RESULT", "PACKAGE_RESULT") + }, + } + env = { + **os.environ, + **results, + "DOCS_ONLY": str(docs_only).lower(), + "REQUIRE_FULL_CI": str(vetted).lower(), + "DEV_REQUIRED": str(developer_tools).lower(), + } + + def run(overrides): + return subprocess.run( + ["bash", "-eu", "-c", script], + env={**env, **overrides}, + capture_output=True, + ).returncode + + assert run({}) == 0 + for name, expected in results.items(): + for outcome in ("success", "skipped", "failure", "cancelled"): + if outcome != expected: + assert run({name: outcome}) != 0, (name, outcome) + for name in ("DOCS_ONLY", "DEV_REQUIRED"): + assert run({name: ""}) != 0, name + + @pytest.mark.parametrize( "missing, ok", [(None, True), (None, False)]