@@ -19,6 +19,10 @@ Thank you for your interest in contributing to CUDA Python! Based on the type of
1919
2020- [ Contributing to CUDA Python] ( #contributing-to-cuda-python )
2121 - [ Table of Contents] ( #table-of-contents )
22+ - [ Cloning the repository] ( #cloning-the-repository )
23+ - [ Recommended clone] ( #recommended-clone )
24+ - [ Fixing an existing clone] ( #fixing-an-existing-clone )
25+ - [ Symptoms of a bad clone] ( #symptoms-of-a-bad-clone )
2226 - [ Type stubs for cuda.core] ( #type-stubs-for-cudacore )
2327 - [ Pre-commit] ( #pre-commit )
2428 - [ Signing Your Work] ( #signing-your-work )
@@ -34,6 +38,94 @@ Thank you for your interest in contributing to CUDA Python! Based on the type of
3438 - [ Code coverage] ( #code-coverage )
3539
3640
41+ ## Cloning the repository
42+
43+ Every package in this repository derives its version from git tags using
44+ [ ` setuptools-scm ` ] ( https://setuptools-scm.readthedocs.io/ ) , so ** how you clone
45+ determines whether you can build at all, and whether the version you build is
46+ correct.** Each package matches its own tag prefix:
47+
48+ | Package | Tag pattern |
49+ | --- | --- |
50+ | ` cuda-bindings ` , ` cuda-python ` | ` v* ` (e.g. ` v13.3.1 ` ) |
51+ | ` cuda-core ` | ` cuda-core-v* ` (e.g. ` cuda-core-v1.1.0 ` ) |
52+ | ` cuda-pathfinder ` | ` cuda-pathfinder-v* ` (e.g. ` cuda-pathfinder-v1.6.0 ` ) |
53+
54+ Each package sets ` root = ".." ` in its ` [tool.setuptools_scm] ` table, meaning the
55+ version is read from the * repository root* rather than the package directory. A
56+ working build therefore needs all of the following:
57+
58+ 1 . ** A real git clone.** Source zips and GitHub "Download ZIP" archives have no
59+ git metadata and the build fails outright. (Tarballs produced by
60+ ` git archive ` do work, thanks to the ` .git_archival.txt ` substitutions
61+ configured in ` .gitattributes ` .)
62+ 2 . ** The full repository** , not just the package subdirectory, because the
63+ version lookup walks up to the repository root.
64+ 3 . ** Tags, reaching back at least as far as the most recent tag** matching the
65+ package you are building. ` git describe ` needs to find that tag; the history
66+ between it and your checkout must be present too.
67+
68+ ### Recommended clone
69+
70+ The default ` git clone ` gives you everything you need:
71+
72+ ``` console
73+ $ git clone https://github.com/NVIDIA/cuda-python.git
74+ ```
75+
76+
77+
78+ ### Fixing an existing clone
79+
80+ If you already have a shallow clone:
81+
82+ ``` console
83+ $ git fetch --unshallow --tags
84+ ```
85+
86+ If you are working from a personal fork, your fork's tags stop tracking upstream
87+ the moment new releases are cut, which silently yields a stale version. Fetch
88+ tags from upstream directly:
89+
90+ ``` console
91+ $ git remote add upstream https://github.com/NVIDIA/cuda-python.git
92+ $ git fetch --tags upstream
93+ ```
94+
95+ Keep doing this periodically — a fork that was correct when you created it will
96+ drift.
97+
98+ ### Symptoms of a bad clone
99+
100+ Only case 3 below reports an error. The first two fail * silently* , producing a
101+ wrong version that surfaces much later as a confusing dependency-resolution or
102+ version-check failure:
103+
104+ 1 . ** No tags reachable.** The build succeeds and produces a version starting at
105+ ` 0.1.dev ` : a ` --depth 1 ` clone yields ` 0.1.dev1+g0d22cb444 ` , a full clone made
106+ with ` --no-tags ` yields ` 0.1.dev2114+g0d22cb444 ` . Installing ` cuda-python `
107+ built this way then fails, because its ` install_requires ` pins
108+ ` cuda-bindings ` to that same bogus version.
109+ 2 . ** Stale tags** (a fork that has not fetched upstream in a while): you get a
110+ plausible-looking but wrong version, e.g. ` 13.0.4.dev650+g0d22cb44 ` when the
111+ real latest tag is ` v13.3.1 ` . Nothing warns you. Note there is no leading
112+ ` v ` — the tag prefix is stripped by ` tag_regex ` .
113+ 3 . ** No git metadata** (source zip): the build fails with
114+ ` LookupError: setuptools-scm was unable to detect version ` .
115+
116+ As a last resort — for example when building inside a container that has no git
117+ history — you can bypass the lookup entirely:
118+
119+ ``` console
120+ $ SETUPTOOLS_SCM_PRETEND_VERSION_FOR_CUDA_CORE=1.1.0 pip install ./cuda_core
121+ ```
122+
123+ The environment variable is suffixed with the distribution name, uppercased with
124+ hyphens replaced by underscores: ` ..._FOR_CUDA_BINDINGS ` , ` ..._FOR_CUDA_CORE ` ,
125+ ` ..._FOR_CUDA_PATHFINDER ` , ` ..._FOR_CUDA_PYTHON ` . Use this only when you
126+ genuinely cannot provide tags; it is not a substitute for a correct clone.
127+
128+
37129## Type stubs for cuda.core
38130
39131` cuda.core ` is a PEP 561-compliant package: it ships a ` py.typed ` marker and
0 commit comments