@@ -22,3 +22,88 @@ The canonical `NVIDIA/cuda-python` repository does not need this variable
2222because its standard workflow behavior is enabled directly. Before enabling a
2323customization elsewhere, document the repository-specific prerequisites and
2424verification procedure in that repository's own documentation.
25+
26+ ## CUDA Bindings Package-Root Registry
27+
28+ ` ci/versions.yml ` is the authoritative public registry for CUDA bindings
29+ package roots. Each mapping key is a repository-relative package root; its
30+ record declares an exact toolkit build/test pin and a ` release_status ` of
31+ ` current ` or ` maintenance ` . Release routing uses the tag's CUDA major/minor
32+ and the toolkit pin to select a root. Bindings and metapackage builds use
33+ setuptools-scm's default tag parser. Each root's ` git_describe_command `
34+ selects its tag series for source builds; update its ` --match ` pattern when
35+ the root moves to a new toolkit minor.
36+
37+ The Python helpers share registry parsing and validation, so they are modules
38+ in the repository-private ` cuda-python-ci-tools ` distribution rather than
39+ standalone scripts with repeated PEP 723 dependency metadata. Install the
40+ package in editable mode from the repository root:
41+
42+ ``` console
43+ python -m pip install -e ./ci
44+ ```
45+
46+ Use ` ci.tools.bindings_config ` instead of reading the YAML directly. It
47+ validates the registry and emits normalized JSON with the configured values
48+ plus the derived CTK target and CUDA ABI major/variant:
49+
50+ ``` console
51+ python -m ci.tools.bindings_config
52+ python -m ci.tools.bindings_config --package-roots
53+ python -m ci.tools.bindings_config --release-status current
54+ ```
55+
56+ Install the test extra to run the CI-tool tests:
57+
58+ ``` console
59+ python -m pip install -e './ci[test]'
60+ python -m pytest --noconftest ci/tools/tests
61+ ```
62+
63+ The public wheel builder requires one ` current ` package root and one
64+ ` maintenance ` package root with different CUDA ABI majors.
65+
66+ ## Maintaining Both Bindings Roots
67+
68+ ` main ` is the source of truth for both bindings release lines. The old
69+ ` 12.9.x ` branch remains available as a record of earlier releases; develop
70+ new CUDA 12 fixes and releases in ` cuda_bindings_12/ ` on ` main ` . The
71+ [ CUDA 12 maintenance guide] ( ../cuda_bindings_12/MAINTENANCE.md ) identifies the
72+ maintenance root.
73+
74+ For generated bindings, change cybind first and regenerate each affected
75+ package root against its intended toolkit inputs. Review the generated diff,
76+ record the cybind revision, toolkit inputs, and command in the pull request,
77+ and check modified files with
78+ ` python toolshed/check_generated_file_seals.py <paths...> ` . The seal verifies
79+ the content of an individual generated file; it does not identify the cybind
80+ revision or prove that the two roots should have identical output. Generated
81+ output may legitimately differ across toolkit targets.
82+
83+ For a handwritten bindings fix, inspect the corresponding code in the other
84+ root. In the pull request, identify the matching change or explain concretely
85+ why the fix does not apply there. A reviewer must verify that judgment: there
86+ is no general deterministic check for semantic equivalence of handwritten
87+ code across the two roots. Where files are intentionally identical, a narrowly
88+ scoped byte-for-byte check can be added after establishing that invariant.
89+
90+ ## Changing Supported Release Lines
91+
92+ When support moves from CUDA 12/13 to CUDA 13/14, keep the CUDA 13 source in
93+ its own package root while introducing a distinct CUDA 14 root. Decide the
94+ root names as part of that change; do not replace the current root's source
95+ until the CUDA 13 maintenance source has a home. Then:
96+
97+ 1 . Update ` ci/versions.yml ` : remove the retired CUDA 12 root, mark the CUDA
98+ 13 root ` maintenance ` , mark the CUDA 14 root ` current ` , and set each exact
99+ toolkit build/test version.
100+ 2 . Align each root's ` pyproject.toml ` ` git_describe_command --match ` selector
101+ and version fallback with its release family. Update other per-root packaging,
102+ pixi environments, documentation, and dependent package constraints for the
103+ supported lines.
104+ 3 . Build and test both roots and their dependent packages on the supported
105+ platforms. Validate release selection and run publication-incapable dry
106+ runs for tags from each line before releasing from the new layout.
107+
108+ The same branch policy applies after the rollover: ` main ` owns the current
109+ and maintenance roots; retired release branches are retained for history.
0 commit comments