From 5737e30d1a45acdb9ad254e26cbdc379ef7ff548 Mon Sep 17 00:00:00 2001 From: Jason Pascucci Date: Thu, 5 Nov 2026 10:12:05 -0800 Subject: [PATCH 1/3] CI: use shallow, blob-filtered CCCL submodule checkouts closes #3351 actions/checkout applies its blob filter only to the root repository, leaving CCCL submodule clones unfiltered and causing slow, variable checkout times. Fetch submodules separately with --depth=1 --filter=blob:none across build, source-test, coverage, and rendered-documentation jobs. Preserve full root history and release tags for setuptools-scm, plus URL syncing and forced checkout for reused workspaces. Validation: fresh and reused checkout checks passed; nine workflow regression tests passed. Actionlint diagnostics are unchanged. Windows checkout timing remains unverified. --- .github/workflows/build-wheel.yml | 9 ++++++-- .github/workflows/ci-pixi-source-test.yml | 27 ++++++++++++++++++----- .github/workflows/coverage.yml | 18 +++++++++++---- .github/workflows/lychee.yml | 10 +++++++-- .github/workflows/test-sdist-linux.yml | 8 ++++++- .github/workflows/test-sdist-windows.yml | 8 ++++++- ci/README.md | 19 ++++++++++++++++ 7 files changed, 83 insertions(+), 16 deletions(-) diff --git a/.github/workflows/build-wheel.yml b/.github/workflows/build-wheel.yml index 14efc9f798b..e757228cc49 100644 --- a/.github/workflows/build-wheel.yml +++ b/.github/workflows/build-wheel.yml @@ -72,8 +72,13 @@ jobs: # but not historical blobs. fetch-depth: 0 filter: blob:none - # third_party/cccl provides the CCCL headers cuda.core compiles against. - submodules: true + # Fetch CCCL separately: checkout's filter does not apply to submodules. + submodules: false + + - name: Checkout CCCL submodule + run: | + git submodule sync --recursive + git submodule update --init --force --depth=1 --filter=blob:none --recursive - name: Register problem matchers # Compiler and Cython errors from the wheel builds become annotations diff --git a/.github/workflows/ci-pixi-source-test.yml b/.github/workflows/ci-pixi-source-test.yml index a09f2e2756f..1e10d2a5a42 100644 --- a/.github/workflows/ci-pixi-source-test.yml +++ b/.github/workflows/ci-pixi-source-test.yml @@ -88,8 +88,13 @@ jobs: # cuda.core's "cuda.bindings 12.x or 13.x must be installed" guard. fetch-depth: 0 filter: blob:none - # third_party/cccl provides the CCCL headers cuda.core compiles against. - submodules: true + # Fetch CCCL separately: checkout's filter does not apply to submodules. + submodules: false + + - name: Checkout CCCL submodule + run: | + git submodule sync --recursive + git submodule update --init --force --depth=1 --filter=blob:none --recursive - name: Setup pixi uses: ./.github/actions/setup-pixi @@ -147,8 +152,13 @@ jobs: # cuda.core's "cuda.bindings 12.x or 13.x must be installed" guard. fetch-depth: 0 filter: blob:none - # third_party/cccl provides the CCCL headers cuda.core compiles against. - submodules: true + # Fetch CCCL separately: checkout's filter does not apply to submodules. + submodules: false + + - name: Checkout CCCL submodule + run: | + git submodule sync --recursive + git submodule update --init --force --depth=1 --filter=blob:none --recursive - name: Setup pixi uses: ./.github/actions/setup-pixi @@ -215,8 +225,13 @@ jobs: # cuda.core's "cuda.bindings 12.x or 13.x must be installed" guard. fetch-depth: 0 filter: blob:none - # third_party/cccl provides the CCCL headers cuda.core compiles against. - submodules: true + # Fetch CCCL separately: checkout's filter does not apply to submodules. + submodules: false + + - name: Checkout CCCL submodule + run: | + git submodule sync --recursive + git submodule update --init --force --depth=1 --filter=blob:none --recursive - name: Setup proxy cache uses: nv-gha-runners/setup-proxy-cache@main diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml index f75ac200b06..50d168db042 100644 --- a/.github/workflows/coverage.yml +++ b/.github/workflows/coverage.yml @@ -71,8 +71,13 @@ jobs: # but not historical blobs. fetch-depth: 0 filter: blob:none - # third_party/cccl provides the CCCL headers cuda.core compiles against. - submodules: true + # Fetch CCCL separately: checkout's filter does not apply to submodules. + submodules: false + + - name: Checkout CCCL submodule + run: | + git submodule sync --recursive + git submodule update --init --force --depth=1 --filter=blob:none --recursive - name: Fix workspace ownership run: | @@ -238,8 +243,13 @@ jobs: # but not historical blobs. fetch-depth: 0 filter: blob:none - # third_party/cccl provides the CCCL headers cuda.core compiles against. - submodules: true + # Fetch CCCL separately: checkout's filter does not apply to submodules. + submodules: false + + - name: Checkout CCCL submodule + run: | + git submodule sync --recursive + git submodule update --init --force --depth=1 --filter=blob:none --recursive - name: Set up Python uses: $/.github/actions/setup-hardened-python diff --git a/.github/workflows/lychee.yml b/.github/workflows/lychee.yml index ecb609ef395..f8f79822b64 100644 --- a/.github/workflows/lychee.yml +++ b/.github/workflows/lychee.yml @@ -63,8 +63,14 @@ jobs: # Keep SCM history/tags without downloading historical source blobs. filter: blob:none persist-credentials: false - # Rendered docs build cuda.core against the pinned CCCL headers. - submodules: ${{ matrix.kind == 'rendered' }} + # Fetch CCCL separately: checkout's filter does not apply to submodules. + submodules: false + + - name: Checkout CCCL submodule + if: ${{ matrix.kind == 'rendered' }} + run: | + git submodule sync --recursive + git submodule update --init --force --depth=1 --filter=blob:none --recursive - name: Set up Python id: python diff --git a/.github/workflows/test-sdist-linux.yml b/.github/workflows/test-sdist-linux.yml index a4dad6edbc5..542ba2ebc93 100644 --- a/.github/workflows/test-sdist-linux.yml +++ b/.github/workflows/test-sdist-linux.yml @@ -47,7 +47,13 @@ jobs: # the commit graph (`git describe`) but not historical blobs. fetch-depth: 0 filter: blob:none - submodules: true + # Fetch CCCL separately: checkout's filter does not apply to submodules. + submodules: false + + - name: Checkout CCCL submodule + run: | + git submodule sync --recursive + git submodule update --init --force --depth=1 --filter=blob:none --recursive - name: Set up Python uses: ./.github/actions/setup-hardened-python diff --git a/.github/workflows/test-sdist-windows.yml b/.github/workflows/test-sdist-windows.yml index bffcf5d2ea9..0c0563126d1 100644 --- a/.github/workflows/test-sdist-windows.yml +++ b/.github/workflows/test-sdist-windows.yml @@ -56,7 +56,13 @@ jobs: # the commit graph (`git describe`) but not historical blobs. fetch-depth: 0 filter: blob:none - submodules: true + # Fetch CCCL separately: checkout's filter does not apply to submodules. + submodules: false + + - name: Checkout CCCL submodule + run: | + git submodule sync --recursive + git submodule update --init --force --depth=1 --filter=blob:none --recursive - name: Set up Python uses: ./.github/actions/setup-hardened-python diff --git a/ci/README.md b/ci/README.md index 2fcd5b4ab1d..af468a8c745 100644 --- a/ci/README.md +++ b/ci/README.md @@ -24,6 +24,25 @@ The pinned checkout action's [`README`](https://github.com/actions/checkout/blob/3d3c42e5aac5ba805825da76410c181273ba90b1/README.md#fetch-all-history-for-all-tags-and-branches) documents `fetch-depth: 0` for fetching all history, branches, and tags. +## CCCL Submodule Checkout + +Jobs that build `cuda.core` fetch its pinned CCCL headers in a separate step: +set `submodules: false` on `actions/checkout`, then run: + +```bash +git submodule sync --recursive +git submodule update --init --force --depth=1 --filter=blob:none --recursive +``` + +The checkout action's `filter` input applies only to the root repository, so +letting it fetch submodules downloads CCCL's unfiltered history. The separate +step limits submodule history to one commit and skips historical blobs, while +checking out the exact revision pinned by the root repository. Syncing URLs +and forcing checkout preserve the action's behavior on reused workspaces. +Keep `fetch-depth: 0` and `filter: blob:none` on the root checkout: package +versioning still needs its complete ancestry and release tags. See +[issue #3351](https://github.com/NVIDIA/cuda-python/issues/3351). + ## Documentation Link Checks Two pre-commit hooks check links with one pinned native wheel (`lychee-bin`, From 4719e3a91558c13ebc5416913c8eecaea2c2cf58 Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Thu, 5 Nov 2026 11:54:04 -0800 Subject: [PATCH 2/3] docs: use filtered shallow CCCL checkouts for contributors MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit — codex GPT-6 on behalf of Ralf — Preserve root history and release tags while fetching CCCL separately with shallow history and blob filtering. Align the contributor guide and package installation examples, and control submodule fetches explicitly on updates. Signed-off-by: Ralf W. Grosse-Kunstleve --- CONTRIBUTING.md | 25 +++++++++++++++--------- cuda_core/docs/source/install.rst | 26 ++++++++++++++++--------- cuda_pathfinder/docs/source/install.rst | 11 +++++++---- 3 files changed, 40 insertions(+), 22 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index df487ccfdc1..33c2984129e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -72,19 +72,24 @@ running the clone command. From the directory where you want to create the checkout, run: ```console -$ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules https://github.com/NVIDIA/cuda-python.git +$ git clone --config core.symlinks=true --config submodule.recurse=true --filter=blob:none https://github.com/NVIDIA/cuda-python.git $ cd cuda-python +$ git submodule update --init --depth=1 --filter=blob:none --recursive ``` This recipe sets up the repository for source builds and development: - `core.symlinks=true` materializes symlinks during checkout, including the build-critical `cuda_core/_build_shared.py`. -- `--recurse-submodules` initializes the CCCL headers needed to build `cuda.core`. +- The separate submodule update initializes the pinned CCCL headers needed to + build `cuda.core`, fetching only one commit of submodule history. +- `--filter=blob:none` skips historical file contents in both repositories. + Git downloads file contents as needed for checkout. - `submodule.recurse=true` keeps initialized submodules in sync on `git pull`, `git checkout`, and `git switch`. -- The clone retains history and release tags for correct package versions. - Do not add `--depth` or `--no-tags`. +- The root clone retains history and release tags for correct package versions. + Do not add `--depth` or `--no-tags` to `git clone`; the depth limit applies + only to submodules. Both configuration settings are stored in the new clone. Next, follow the build and test instructions for @@ -97,13 +102,15 @@ build and test instructions for From the repository root, run: ```console -$ git pull --recurse-submodules -$ git submodule update --init +$ git pull --no-recurse-submodules +$ git submodule sync --recursive +$ git submodule update --init --depth=1 --filter=blob:none --recursive ``` -The recommended clone configures `submodule.recurse=true`, so you can omit -`--recurse-submodules` from `git pull`. The second command initializes any -newly added submodules; it is usually a no-op. +Pull the root repository first, then sync submodule URLs and update the pinned +revisions, including any newly added submodules. The explicit +`--no-recurse-submodules` overrides `submodule.recurse=true` for the pull so +submodules are fetched separately with the requested depth and filter. If you work from a fork, periodically fetch release tags from NVIDIA upstream so package versions stay current: diff --git a/cuda_core/docs/source/install.rst b/cuda_core/docs/source/install.rst index 0b4374392b9..e67bb03c202 100644 --- a/cuda_core/docs/source/install.rst +++ b/cuda_core/docs/source/install.rst @@ -130,24 +130,29 @@ recipe below. On native Windows outside WSL, complete its Windows setup .. code-block:: console - $ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules https://github.com/NVIDIA/cuda-python.git - $ cd cuda-python/cuda_core + $ git clone --config core.symlinks=true --config submodule.recurse=true --filter=blob:none https://github.com/NVIDIA/cuda-python.git + $ cd cuda-python + $ git submodule update --init --depth=1 --filter=blob:none --recursive + $ cd cuda_core $ pip install . .. note:: - ``--recurse-submodules`` is required: the build compiles against the CCCL + The submodule update is required: the build compiles against the CCCL headers pinned in the ``cuda_core/third_party/cccl`` submodule, and fails without them. For a clone that already exists, run the following from the repository root: - ``git submodule update --init cuda_core/third_party/cccl``. + ``git submodule update --init --depth=1 --filter=blob:none --recursive``. + Only the submodule history is shallow; the root clone retains its history + and release tags. .. note:: The version is derived from git tags via ``setuptools-scm``, so the clone must include tags reaching back to at least the latest ``cuda-core-v*`` tag. - Do not use ``--depth`` or ``--no-tags``: a shallow clone builds without - error but produces a bogus version such as ``0.1.dev1+g0d22cb444``. See + Do not add ``--depth`` or ``--no-tags`` to ``git clone``: a shallow root + clone builds without error but produces a bogus version such as + ``0.1.dev1+g0d22cb444``. See `Cloning the repository `_ for details. @@ -161,8 +166,10 @@ For example, to work on ``cuda-core`` against CUDA 13: .. code-block:: console - $ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules https://github.com/NVIDIA/cuda-python.git - $ cd cuda-python/cuda_core + $ git clone --config core.symlinks=true --config submodule.recurse=true --filter=blob:none https://github.com/NVIDIA/cuda-python.git + $ cd cuda-python + $ git submodule update --init --depth=1 --filter=blob:none --recursive + $ cd cuda_core $ uv venv $ source .venv/bin/activate # On Windows: .venv\Scripts\activate $ uv pip install -e .[cu13] --group test @@ -184,8 +191,9 @@ For example, to work against CUDA 13: .. code-block:: console - $ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules https://github.com/NVIDIA/cuda-python.git + $ git clone --config core.symlinks=true --config submodule.recurse=true --filter=blob:none https://github.com/NVIDIA/cuda-python.git $ cd cuda-python + $ git submodule update --init --depth=1 --filter=blob:none --recursive $ pixi run -e cu13 test-core To run all repository tests (pathfinder → bindings → core): diff --git a/cuda_pathfinder/docs/source/install.rst b/cuda_pathfinder/docs/source/install.rst index 6c2acbdd69a..dad1a36224c 100644 --- a/cuda_pathfinder/docs/source/install.rst +++ b/cuda_pathfinder/docs/source/install.rst @@ -64,8 +64,10 @@ before cloning. .. code-block:: console - $ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules https://github.com/NVIDIA/cuda-python.git - $ cd cuda-python/cuda_pathfinder + $ git clone --config core.symlinks=true --config submodule.recurse=true --filter=blob:none https://github.com/NVIDIA/cuda-python.git + $ cd cuda-python + $ git submodule update --init --depth=1 --filter=blob:none --recursive + $ cd cuda_pathfinder $ pip install . For an editable install (e.g. when developing ``cuda.pathfinder`` itself): @@ -78,8 +80,9 @@ For an editable install (e.g. when developing ``cuda.pathfinder`` itself): The version is derived from git tags via ``setuptools-scm``, so the clone must include tags reaching back to at least the latest ``cuda-pathfinder-v*`` - tag. Do not use ``--depth`` or ``--no-tags``: a shallow clone builds without - error but produces a bogus version such as ``0.1.dev1+g0d22cb444``. See + tag. Do not add ``--depth`` or ``--no-tags`` to ``git clone``: a shallow root + clone builds without error but produces a bogus version such as + ``0.1.dev1+g0d22cb444``. See `Cloning the repository `_ for details. From 25fc8134b13ed239a0603f17004289e1d9ba60b6 Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Thu, 5 Nov 2026 12:18:03 -0800 Subject: [PATCH 3/3] docs: simplify filtered clone instructions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit — codex GPT-6 on behalf of Ralf — Use Git's native submodule filtering in each clone example and retain the ordinary update instructions. Preserve full commit history and release tags while keeping the filtered recipe directly visible to users and agents. Signed-off-by: Ralf W. Grosse-Kunstleve --- CONTRIBUTING.md | 31 +++++++++++-------------- cuda_core/docs/source/install.rst | 26 +++++++-------------- cuda_pathfinder/docs/source/install.rst | 11 ++++----- 3 files changed, 27 insertions(+), 41 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 33c2984129e..b614fdcc1e0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -69,27 +69,26 @@ ran and any validation gaps. including the Developer Mode registry check.** Complete that setup before running the clone command. -From the directory where you want to create the checkout, run: +With Git 2.36 or newer, run this from the directory where you want to +create the checkout: ```console -$ git clone --config core.symlinks=true --config submodule.recurse=true --filter=blob:none https://github.com/NVIDIA/cuda-python.git +$ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules --filter=blob:none --also-filter-submodules https://github.com/NVIDIA/cuda-python.git $ cd cuda-python -$ git submodule update --init --depth=1 --filter=blob:none --recursive ``` This recipe sets up the repository for source builds and development: - `core.symlinks=true` materializes symlinks during checkout, including the build-critical `cuda_core/_build_shared.py`. -- The separate submodule update initializes the pinned CCCL headers needed to - build `cuda.core`, fetching only one commit of submodule history. -- `--filter=blob:none` skips historical file contents in both repositories. - Git downloads file contents as needed for checkout. +- `--recurse-submodules` initializes the CCCL headers needed to build `cuda.core`. +- `--filter=blob:none --also-filter-submodules` skips historical file + contents in the repository and CCCL. Git downloads those contents + when needed; commit history and release tags remain available. - `submodule.recurse=true` keeps initialized submodules in sync on `git pull`, `git checkout`, and `git switch`. -- The root clone retains history and release tags for correct package versions. - Do not add `--depth` or `--no-tags` to `git clone`; the depth limit applies - only to submodules. +- The clone retains history and release tags for correct package versions. + Do not add `--depth` or `--no-tags`. Both configuration settings are stored in the new clone. Next, follow the build and test instructions for @@ -102,15 +101,13 @@ build and test instructions for From the repository root, run: ```console -$ git pull --no-recurse-submodules -$ git submodule sync --recursive -$ git submodule update --init --depth=1 --filter=blob:none --recursive +$ git pull --recurse-submodules +$ git submodule update --init ``` -Pull the root repository first, then sync submodule URLs and update the pinned -revisions, including any newly added submodules. The explicit -`--no-recurse-submodules` overrides `submodule.recurse=true` for the pull so -submodules are fetched separately with the requested depth and filter. +The recommended clone configures `submodule.recurse=true`, so you can omit +`--recurse-submodules` from `git pull`. The second command initializes any +newly added submodules; it is usually a no-op. If you work from a fork, periodically fetch release tags from NVIDIA upstream so package versions stay current: diff --git a/cuda_core/docs/source/install.rst b/cuda_core/docs/source/install.rst index e67bb03c202..e2d74063140 100644 --- a/cuda_core/docs/source/install.rst +++ b/cuda_core/docs/source/install.rst @@ -130,29 +130,24 @@ recipe below. On native Windows outside WSL, complete its Windows setup .. code-block:: console - $ git clone --config core.symlinks=true --config submodule.recurse=true --filter=blob:none https://github.com/NVIDIA/cuda-python.git - $ cd cuda-python - $ git submodule update --init --depth=1 --filter=blob:none --recursive - $ cd cuda_core + $ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules --filter=blob:none --also-filter-submodules https://github.com/NVIDIA/cuda-python.git + $ cd cuda-python/cuda_core $ pip install . .. note:: - The submodule update is required: the build compiles against the CCCL + ``--recurse-submodules`` is required: the build compiles against the CCCL headers pinned in the ``cuda_core/third_party/cccl`` submodule, and fails without them. For a clone that already exists, run the following from the repository root: - ``git submodule update --init --depth=1 --filter=blob:none --recursive``. - Only the submodule history is shallow; the root clone retains its history - and release tags. + ``git submodule update --init cuda_core/third_party/cccl``. .. note:: The version is derived from git tags via ``setuptools-scm``, so the clone must include tags reaching back to at least the latest ``cuda-core-v*`` tag. - Do not add ``--depth`` or ``--no-tags`` to ``git clone``: a shallow root - clone builds without error but produces a bogus version such as - ``0.1.dev1+g0d22cb444``. See + Do not use ``--depth`` or ``--no-tags``: a shallow clone builds without + error but produces a bogus version such as ``0.1.dev1+g0d22cb444``. See `Cloning the repository `_ for details. @@ -166,10 +161,8 @@ For example, to work on ``cuda-core`` against CUDA 13: .. code-block:: console - $ git clone --config core.symlinks=true --config submodule.recurse=true --filter=blob:none https://github.com/NVIDIA/cuda-python.git - $ cd cuda-python - $ git submodule update --init --depth=1 --filter=blob:none --recursive - $ cd cuda_core + $ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules --filter=blob:none --also-filter-submodules https://github.com/NVIDIA/cuda-python.git + $ cd cuda-python/cuda_core $ uv venv $ source .venv/bin/activate # On Windows: .venv\Scripts\activate $ uv pip install -e .[cu13] --group test @@ -191,9 +184,8 @@ For example, to work against CUDA 13: .. code-block:: console - $ git clone --config core.symlinks=true --config submodule.recurse=true --filter=blob:none https://github.com/NVIDIA/cuda-python.git + $ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules --filter=blob:none --also-filter-submodules https://github.com/NVIDIA/cuda-python.git $ cd cuda-python - $ git submodule update --init --depth=1 --filter=blob:none --recursive $ pixi run -e cu13 test-core To run all repository tests (pathfinder → bindings → core): diff --git a/cuda_pathfinder/docs/source/install.rst b/cuda_pathfinder/docs/source/install.rst index dad1a36224c..cf49c40891e 100644 --- a/cuda_pathfinder/docs/source/install.rst +++ b/cuda_pathfinder/docs/source/install.rst @@ -64,10 +64,8 @@ before cloning. .. code-block:: console - $ git clone --config core.symlinks=true --config submodule.recurse=true --filter=blob:none https://github.com/NVIDIA/cuda-python.git - $ cd cuda-python - $ git submodule update --init --depth=1 --filter=blob:none --recursive - $ cd cuda_pathfinder + $ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules --filter=blob:none --also-filter-submodules https://github.com/NVIDIA/cuda-python.git + $ cd cuda-python/cuda_pathfinder $ pip install . For an editable install (e.g. when developing ``cuda.pathfinder`` itself): @@ -80,9 +78,8 @@ For an editable install (e.g. when developing ``cuda.pathfinder`` itself): The version is derived from git tags via ``setuptools-scm``, so the clone must include tags reaching back to at least the latest ``cuda-pathfinder-v*`` - tag. Do not add ``--depth`` or ``--no-tags`` to ``git clone``: a shallow root - clone builds without error but produces a bogus version such as - ``0.1.dev1+g0d22cb444``. See + tag. Do not use ``--depth`` or ``--no-tags``: a shallow clone builds without + error but produces a bogus version such as ``0.1.dev1+g0d22cb444``. See `Cloning the repository `_ for details.