Skip to content

Commit 8fa2bf7

Browse files
Andy-Jostclaude
Andy-Jost
and
claude
authored
[doc-only] docs(cuda.core): define the cuda-bindings floor as the lowest compatible release (#3425)
* docs(cuda.core): define the cuda-bindings floor as the lowest compatible release The written policy said that the floor is the newest cuda-bindings release of each major at the time of a cuda.core release. The intended policy is the opposite: the floor is the oldest release that was generated from the cuda.h major.minor the wheels are built against and that provides every API and fix cuda.core needs. State that rule, the three events that move a floor, and the release checks that replace "bump to newest". No pin, check, or test changes. Co-Authored-By: Claude Fable 5.2 <[email protected]> * docs: make the floor release checks actionable Name the CI run and the log line for the floor check, and say that standard CI does not install the CUDA 12 floor. Require a new floor to be released on PyPI first. Drop a dangling "also". Co-Authored-By: Claude Opus 5.5 <[email protected]> --------- Co-authored-by: Claude Fable 5.2 <[email protected]>
1 parent 5d7fbb6 commit 8fa2bf7

6 files changed

Lines changed: 66 additions & 23 deletions

File tree

‎.github/RELEASE-core.md‎

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -85,9 +85,24 @@ platforms as appropriate for each release.
8585
## Check (or update if needed) the dependency requirements
8686

8787
Review `cuda_core/pyproject.toml` and verify that all dependency
88-
requirements are current. The `cu12`/`cu13` extras declare the
89-
`cuda-bindings` floors; see "Bumping the cuda-bindings floor" in
90-
`cuda_core/AGENTS.md`.
88+
requirements are current.
89+
90+
The `cu12`/`cu13` extras declare the `cuda-bindings` floors. A release
91+
does not raise a floor to the newest `cuda-bindings`; see "Bumping the
92+
cuda-bindings floor" in `cuda_core/AGENTS.md`. Check the floors instead:
93+
94+
- The minor of each floor equals the minor of the toolkit pin of its
95+
major in `ci/versions.yml` (`build` for the current major, `prev_build`
96+
for the prior major). If a floor's minor is lower, the toolkit-bump
97+
window is open: move the floor before the release.
98+
- In the latest CI run on `main`, the CUDA 13 rows whose CUDA minor
99+
differs from the `build` pin (for example "CUDA 13.0.2") installed the
100+
literal floor. Their logs show `Installing bindings (source: floor)` and
101+
`cuda-bindings==<floor>`, and no "predates ... headers" line. Standard
102+
CI does not install the CUDA 12 floor: its rows use the 12.9.x backport
103+
build.
104+
- The release notes list every floor move since the last release under
105+
"Breaking Changes".
91106

92107
Update the `cuda-core` pin in `cuda_python/setup.py` to the new minor
93108
series (`cuda-core~=X.Y.0`), and plan a `cuda-python` release right after

‎cuda_core/AGENTS.md‎

Lines changed: 29 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -51,11 +51,28 @@ This file describes `cuda_core`, the high-level Pythonic CUDA subpackage in the
5151

5252
### Bumping the cuda-bindings floor
5353

54-
By policy, the floor of each major is the newest `cuda-bindings` release of
55-
that major at the time of a `cuda.core` release. The bump is therefore a
56-
release step. A `cuda-bindings` minor release does not trigger it. The first
57-
change that uses a `cuda-bindings` API newer than the old floor also requires
58-
a bump. To bump:
54+
By policy, the floor of each major is the oldest `cuda-bindings` release that
55+
meets two conditions. It was generated from the `cuda.h` major.minor that the
56+
`cuda.core` wheels are built against, the toolkit pin of that major in
57+
`ci/versions.yml`. It provides every `cuda-bindings` API that `cuda.core` uses
58+
and every fix that `cuda.core` relies on. The floor's minor therefore equals
59+
the build toolkit's minor, and the floor's patch is the lowest one that
60+
qualifies.
61+
62+
Three events move a floor:
63+
64+
- A change uses a `cuda-bindings` API newer than the floor. Bump the floor in
65+
the same pull request. The new floor must already be released on PyPI;
66+
release `cuda-bindings` first.
67+
- A change relies on a bug fix in a newer `cuda-bindings`. Bump the floor in
68+
the same pull request, under the same condition.
69+
- The build toolkit moves to a new minor. Move the floor to the lowest
70+
suitable release of that minor, as described under "CUDA Toolkit minor
71+
bumps".
72+
73+
Nothing else moves a floor. A new `cuda-bindings` release does not, and a
74+
`cuda.core` release does not. Do not raise a floor to the newest release. To
75+
bump:
5976

6077
1. Edit the `cuda-bindings` pin in the `cu12` or `cu13` extra in
6178
`pyproject.toml`. That is the only version to type.
@@ -74,7 +91,7 @@ a bump. To bump:
7491
5. Pin `cuda-bindings` to match in the conda-forge `cuda-core` feedstock. The
7592
feedstock lives outside this repository.
7693

77-
A `cuda-core` release also bumps the `cuda-core~=X.Y.0` pin in
94+
A `cuda-core` release bumps the `cuda-core~=X.Y.0` pin in
7895
`cuda_python/setup.py`, followed by a `cuda-python` release (see
7996
`.github/RELEASE-core.md`).
8097

@@ -98,7 +115,12 @@ the literal floor, until the floor is bumped. The order is:
98115

99116
1. Bump the toolkit.
100117
2. Release `cuda-bindings` for the new minor.
101-
3. Bump the floor here.
118+
3. Move the floor here to the lowest suitable release of the new minor. That
119+
is normally its first release.
120+
121+
A `cuda.core` release must not ship while the window is open. In the window,
122+
the `cu<major>` extra can resolve to a `cuda-bindings` that fails the header
123+
check at import, and CI does not test the literal floor.
102124

103125
## Testing expectations
104126

‎cuda_core/cuda/core/_bindings_floor.py‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,13 @@
66
77
cuda.core supports two CUDA major series at a time. For each series, it
88
requires a minimum cuda-bindings version, the *floor*, at build time and at
9-
run time. The floor is the newest cuda-bindings release of that series at the
10-
time of the cuda.core release. Normally that is the release that the cuda.core
11-
wheels are built against. See https://github.com/NVIDIA/cuda-python/issues/2783
12-
and the support policy in the documentation.
9+
run time. The floor is the oldest cuda-bindings release of that series that
10+
meets two conditions. It was generated from the ``cuda.h`` major.minor that the
11+
cuda.core wheels are built against. It provides every cuda-bindings API and fix
12+
that cuda.core needs. A new cuda-bindings release does not move the floor, and
13+
a cuda.core release does not. See
14+
https://github.com/NVIDIA/cuda-python/issues/2783 and the support policy in the
15+
documentation.
1316
1417
Exactly one place declares the floors: the ``cu12`` and ``cu13`` extras in
1518
``pyproject.toml``. Each extra pins ``cuda-bindings>=<floor>,<<next major>``.

‎cuda_core/cuda/core/_device_resources.pyx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -214,7 +214,7 @@ cdef int _structured_split_checked = 0
214214
cdef inline bint _can_use_structured_sm_split():
215215
"""Whether the driver provides cuDevSmResourceSplit, a 13.1 driver API. Cached.
216216
217-
Every cuda-bindings at or above the 13.4 floor exports it. Only the driver can lack it."""
217+
Every cuda-bindings at or above the CUDA 13 floor exports it. Only the driver can lack it."""
218218
global _structured_split_checked
219219
if _structured_split_checked != 0:
220220
return _structured_split_checked == 1

‎cuda_core/cuda/core/_memory/_copy_attributes.pxd‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ from cuda.core._utils.version cimport cy_driver_version # no-cython-lint
1313
IF CUDA_CORE_BUILD_MAJOR >= 13:
1414
cdef inline bint _with_attributes_available():
1515
# cuMemcpyWithAttributesAsync is a 13.2 driver API. Every cuda-bindings at
16-
# or above the 13.4 floor exports it, so only the driver can lack it.
16+
# or above the CUDA 13 floor exports it, so only the driver can lack it.
1717
return cy_driver_version() >= (13, 2, 0)
1818
ELSE:
1919
cdef inline bint _with_attributes_available():

‎cuda_core/docs/source/support.rst‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -70,10 +70,12 @@ CUDA library or CUDA driver versions. Refer to the individual module documentati
7070
**************************************
7171

7272
For each supported CUDA major version, each ``cuda-core`` release declares a minimum
73-
``cuda-bindings`` version, its *floor*. The floor is the newest ``cuda-bindings`` release of that
74-
major at the time of the ``cuda-core`` release. The published wheels are built against it. The
75-
``cu12`` and ``cu13`` extras of ``cuda-core`` in ``pyproject.toml`` declare the floors of the
76-
current release. The build, the import-time check, this page, and CI all read them from there.
73+
``cuda-bindings`` version, its *floor*. The floor is the oldest ``cuda-bindings`` release that
74+
meets two conditions. It was generated from the ``cuda.h`` major.minor that the published
75+
``cuda-core`` wheels are built against. It provides every ``cuda-bindings`` API and fix that
76+
``cuda-core`` needs. The ``cu12`` and ``cu13`` extras of ``cuda-core`` in ``pyproject.toml``
77+
declare the floors of the current release. The build, the import-time check, this page, and CI
78+
all read them from there.
7779

7880
.. list-table:: ``cuda-bindings`` floors
7981
:header-rows: 1
@@ -102,9 +104,10 @@ current release. The build, the import-time check, this page, and CI all read th
102104
features. In that case ``cuda-core`` never crashes or returns a wrong result; depending on the
103105
feature, it may raise an error or emulate the feature.
104106

105-
A floor moves with each ``cuda-core`` release, to the newest ``cuda-bindings`` of each major at
106-
that time. It also moves in any release whose changes need a newer ``cuda-bindings`` API. The
107-
:doc:`release notes <release>` list every move under "Breaking Changes".
107+
A floor moves only for one of two reasons. A ``cuda-core`` release needs a newer
108+
``cuda-bindings`` API or fix, or its wheels are built against a newer CUDA minor version. A new
109+
``cuda-bindings`` release alone does not move a floor, and a ``cuda-core`` release alone does
110+
not. The :doc:`release notes <release>` list every move under "Breaking Changes".
108111

109112
Python Version Support
110113
----------------------

0 commit comments

Comments
 (0)