Skip to content

Commit 226e394

Browse files
Andy-Jostclaude
Andy-Jost
and
claude
committed
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]>
1 parent fe9bb74 commit 226e394

6 files changed

Lines changed: 61 additions & 22 deletions

File tree

‎.github/RELEASE-core.md‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -85,9 +85,21 @@ 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+
- The CI rows with `BINDINGS_SOURCE=floor` installed the literal floor.
99+
Their logs show `cuda-bindings==<floor>` and no "predates ... headers"
100+
line.
101+
- The release notes list every floor move since the last release under
102+
"Breaking Changes".
91103

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

‎cuda_core/AGENTS.md‎

Lines changed: 27 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -51,11 +51,27 @@ 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.
66+
- A change relies on a bug fix in a newer `cuda-bindings`. Bump the floor in
67+
the same pull request.
68+
- The build toolkit moves to a new minor. Move the floor to the lowest
69+
suitable release of that minor, as described under "CUDA Toolkit minor
70+
bumps".
71+
72+
Nothing else moves a floor. A new `cuda-bindings` release does not, and a
73+
`cuda.core` release does not. Do not raise a floor to the newest release. To
74+
bump:
5975

6076
1. Edit the `cuda-bindings` pin in the `cu12` or `cu13` extra in
6177
`pyproject.toml`. That is the only version to type.
@@ -98,7 +114,12 @@ the literal floor, until the floor is bumped. The order is:
98114

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

103124
## Testing expectations
104125

‎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)