Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 46 additions & 8 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -79,6 +88,7 @@ jobs:
retention-days: 14

lint:
needs: changes
timeout-minutes: 15
name: lint
runs-on: ubuntu-24.04
Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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 }}
Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/docs-preview.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
32 changes: 25 additions & 7 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
`pull-request/<number>` 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 <full-head-SHA>`. A maintainer can also push that same reviewed
commit to `pull-request/<number>` 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.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
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
Expand Down
1 change: 1 addition & 0 deletions MANIFEST.in
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 5 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
126 changes: 126 additions & 0 deletions scripts/ci_changes.py
Original file line number Diff line number Diff line change
@@ -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")
Comment thread
tpn marked this conversation as resolved.
Resolved
with Path(os.environ["GITHUB_STEP_SUMMARY"]).open("a") as summary:
summary.write(f"CI profile: **{profile}**.\n")


if __name__ == "__main__":
main()
Loading
Loading