From f1cd3ff768ea57ed641e9d52c2e5fc919c0b2907 Mon Sep 17 00:00:00 2001 From: Ralf Juengling Date: Thu, 1 Oct 2026 14:38:12 -0700 Subject: [PATCH 1/2] ci: move lychee excludes to lychee.toml Move the link-checker excludes out of build-docs.yml into a repo-root lychee.toml, and point the workflow at it with --config. This keeps the exclude list and its explanatory comments in one place. No behavior change. --- .github/workflows/build-docs.yml | 8 +------- lychee.toml | 15 +++++++++++++++ 2 files changed, 16 insertions(+), 7 deletions(-) create mode 100644 lychee.toml diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index 03ad9463b06..52ee9698ab0 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -309,10 +309,6 @@ jobs: if: ${{ !inputs.is-release && startsWith(github.ref_name, 'pull-request/') }} uses: lycheeverse/lychee-action@6da1d14f3a43098a294b7696d93d938aa8d20fc0 # unreleased: supports v0.24.x archive layout with: - # PR-preview canonical URLs are checked by the preview deployment workflow. - # The cuda-bindings #id links are docutils "problematic" anchors from generated API docs. - # TODO: Remove this exclusion after cybind stops emitting those problematic anchors. - # Preferred Networks rejects hosted-runner GETs, but the URL is browser reachable. args: >- --files-from ${{ github.workspace }}/lychee-rendered-html-files.txt --include-fragments=full @@ -325,9 +321,7 @@ jobs: --retry-wait-time 5 --timeout 30 --no-progress - --exclude '^https://nvidia\.github\.io/cuda-python/pr-preview/pr-[0-9]+/' - --exclude '^file://.*/cuda-bindings/latest/module/(driver|runtime)\.html#id[0-9]+$' - --exclude '^https://www\.preferred\.jp/en/?$' + --config ${{ github.workspace }}/lychee.toml fail: true failIfEmpty: true format: markdown diff --git a/lychee.toml b/lychee.toml new file mode 100644 index 00000000000..d72bad9002f --- /dev/null +++ b/lychee.toml @@ -0,0 +1,15 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +# +# Configuration for lychee, the doc link-checker invoked from +# .github/workflows/build-docs.yml. See https://lychee.cli.rs/usage/config/. + +exclude = [ + # PR-preview canonical URLs are checked by the preview deployment workflow. + '^https://nvidia\.github\.io/cuda-python/pr-preview/pr-[0-9]+/', + # The cuda-bindings #id links are docutils "problematic" anchors from generated API docs. + # TODO: Remove this exclusion after cybind stops emitting those problematic anchors. + '^file://.*/cuda-bindings/latest/module/(driver|runtime)\.html#id[0-9]+$', + # Preferred Networks rejects hosted-runner GETs, but the URL is browser reachable. + '^https://www\.preferred\.jp/en/?$', +] From 0ec438cd4dee63a0259b2644307ae0b8179e4b2a Mon Sep 17 00:00:00 2001 From: Ralf Juengling Date: Thu, 1 Oct 2026 14:44:20 -0700 Subject: [PATCH 2/2] ci: enable git symlinks on Windows runners; add Windows dev docs Set core.symlinks=true before checkout in the Windows wheel, wheel-test and sdist-test workflows, and add a "Development on Windows" section to CONTRIBUTING.md covering symlink setup (Developer Mode, core.symlinks). The existing pre-commit lychee workaround moves into that section. --- .github/workflows/build-wheel.yml | 4 ++ .github/workflows/test-sdist-windows.yml | 3 + .github/workflows/test-wheel-windows.yml | 3 + CONTRIBUTING.md | 78 ++++++++++++++++++++---- 4 files changed, 76 insertions(+), 12 deletions(-) diff --git a/.github/workflows/build-wheel.yml b/.github/workflows/build-wheel.yml index 71d714529cb..1146b7693b2 100644 --- a/.github/workflows/build-wheel.yml +++ b/.github/workflows/build-wheel.yml @@ -67,6 +67,10 @@ jobs: (inputs.host-platform == 'win-64' && 'windows-2022') || (inputs.host-platform == 'win-arm64' && 'windows-11-arm') }} steps: + - name: Enable Git symlinks (Windows, must precede checkout) + if: ${{ startsWith(inputs.host-platform, 'win') }} + run: git config --global core.symlinks true + - name: Checkout ${{ github.event.repository.name }} uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: diff --git a/.github/workflows/test-sdist-windows.yml b/.github/workflows/test-sdist-windows.yml index b35f80a2276..0a999e8b41e 100644 --- a/.github/workflows/test-sdist-windows.yml +++ b/.github/workflows/test-sdist-windows.yml @@ -43,6 +43,9 @@ jobs: timeout-minutes: 60 runs-on: windows-2022 steps: + - name: Enable Git symlinks (Windows, must precede checkout) + run: git config --global core.symlinks true + - name: Checkout ${{ github.event.repository.name }} uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: diff --git a/.github/workflows/test-wheel-windows.yml b/.github/workflows/test-wheel-windows.yml index 11512ee7a83..178ad1b13d1 100644 --- a/.github/workflows/test-wheel-windows.yml +++ b/.github/workflows/test-wheel-windows.yml @@ -105,6 +105,9 @@ jobs: continue-on-error: ${{ startsWith(matrix.PY_VER, '3.15') }} runs-on: "windows-${{ matrix.ARCH }}-gpu-${{ matrix.GPU }}-${{ matrix.RUNNER_DRIVER }}-${{ matrix.GPU_COUNT }}" steps: + - name: Enable Git symlinks (Windows, must precede checkout) + run: git config --global core.symlinks true + - name: Checkout ${{ github.event.repository.name }} uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7e5b9400663..8b7b28d475e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,9 +23,11 @@ Thank you for your interest in contributing to CUDA Python! Based on the type of - [Recommended clone](#recommended-clone) - [Fixing an existing clone](#fixing-an-existing-clone) - [Symptoms of a bad clone](#symptoms-of-a-bad-clone) + - [Development on Windows](#development-on-windows) + - [Enabling git symlinks](#enabling-git-symlinks) + - [Pre-commit lychee workaround](#pre-commit-lychee-workaround) - [Type stubs for cuda.core](#type-stubs-for-cudacore) - [Pre-commit](#pre-commit) - - [Pre-commit on Windows](#pre-commit-on-windows) - [Pixi lockfiles](#pixi-lockfiles) - [Signing Your Work](#signing-your-work) - [Code signing](#code-signing) @@ -42,6 +44,11 @@ Thank you for your interest in contributing to CUDA Python! Based on the type of ## Cloning the repository +> **Windows contributors (not WSL):** configure Git for symlinks *before* +> cloning, or the shared PEP 517 build-hook file lands as a text stub instead +> of a working symlink. See [Enabling git symlinks](#enabling-git-symlinks) +> under Development on Windows. + Every package in this repository derives its version from git tags using [`setuptools-scm`](https://setuptools-scm.readthedocs.io/), so **how you clone determines whether you can build at all, and whether the version you build is @@ -128,6 +135,63 @@ hyphens replaced by underscores: `..._FOR_CUDA_BINDINGS`, `..._FOR_CUDA_CORE`, genuinely cannot provide tags; it is not a substitute for a correct clone. +## Development on Windows + +This section collects the Windows-specific setup a contributor needs when +working outside of WSL. WSL contributors can follow the Linux flow in the rest +of this document. + +### Enabling git symlinks + +The `cuda_core` PEP 517 backend shares source-of-truth helper files with +`cuda_bindings` via symbolic links. Git materializes symlinks by default on +Linux and macOS, but on Windows it needs to be configured before cloning, +otherwise the "symlinks" land in your working tree as plain text files that +contain the target path — enough to look right in `git status`, but not enough +to actually build. + +1. **[Activate Developer Mode](https://learn.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development#activate-developer-mode)** + so Git can create symlinks without Administrator privileges. + +2. **Enable Git symlink support globally** so newly-cloned repositories inherit + the setting: + + ```console + $ git config --global core.symlinks true + ``` + +Then clone as usual (see [Cloning the repository](#cloning-the-repository)). + +If you already cloned without these settings, note that `git clone` probes +symlink support at clone time and writes `core.symlinks=false` into the +repo-local config when the probe fails. Repo-local config overrides +`--global`, so you must clear it *inside the existing clone* — the global +setting alone won't take effect: + +```console +$ git config core.symlinks true # no --global — clears the repo-local override +$ git rm --cached cuda_core/_build_shared.py +$ git checkout HEAD -- cuda_core/_build_shared.py +``` + +In practice, deleting the checkout and re-cloning after the two steps at +the top of this section (Developer Mode + `git config --global core.symlinks +true`) is usually simpler and less error-prone than repairing an existing +clone in place. + +### Pre-commit lychee workaround + +For development on Windows (not WSL), the `lychee` pre-commit task will not +work when running `pre-commit run --all-files`. This problem does not occur +if you install the pre-commit hook and run it automatically as part of your +`git commit` workflow. To resolve this, you can either: + +1. Run `pre-commit` in Git Bash, rather than directly in PowerShell or cmd + +2. Skip it by setting the environment variable `SKIP` to `lychee`. This would + be `$env:SKIP = "lychee"` in PowerShell or `set SKIP=lychee` in cmd. + + ## Type stubs for cuda.core `cuda.core` is a PEP 561-compliant package: it ships a `py.typed` marker and @@ -168,17 +232,7 @@ between commits, leaving stale headers or out-of-date stubs in the history. If the hook isn't installed, `pre-commit run` (and CI) will print a visible warning reminding you to run `pre-commit install`. -### Pre-commit on Windows - -For development on Windows (not WSL), the `lychee` pre-commit task will not work -when running `pre-commit run --all-files`. This problem does not occur if you -install the pre-commit hook and run it automatically as part of your `git -commit` workflow. To resolve this, you can either: - -1. Run `pre-commit` in Git Bash, rather than directly in PowerShell or cmd - -2. Skip it by setting the environment variable `SKIP` to `lychee`. This would - be `$env:SKIP = "lychee"` in PowerShell or `set SKIP=lychee` in cmd. +Windows contributors: see [Pre-commit lychee workaround](#pre-commit-lychee-workaround) under Development on Windows. ## Pixi lockfiles