|
| 1 | +<!-- |
| 2 | +SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. |
| 3 | +SPDX-License-Identifier: Apache-2.0 |
| 4 | +--> |
| 5 | + |
| 6 | +# Releasing CUDA bindings |
| 7 | + |
| 8 | +## Choose the release scope and source |
| 9 | + |
| 10 | +Develop the current and maintenance CUDA major lines together on `main`, in |
| 11 | +the two package roots listed in [`ci/versions.yml`](../ci/versions.yml). |
| 12 | +Release each line independently. A bindings release also needs its matching |
| 13 | +`cuda-python` metapackage release; it does not require a release of the other |
| 14 | +CUDA major, `cuda-core`, or `cuda-pathfinder`. |
| 15 | + |
| 16 | +Major-line maintenance may include selected API, Python, platform, or other |
| 17 | +compatibility changes. Decide those changes explicitly and describe them in |
| 18 | +the release notes. Once a patch release is frozen, admit only its approved |
| 19 | +fixes and release prerequisites. Do not infer patch-release scope solely |
| 20 | +from the registry's `maintenance` role. |
| 21 | + |
| 22 | +For an ordinary release, select a tested commit on `main`. If stabilization |
| 23 | +must continue while development advances, create a short release branch such |
| 24 | +as `release/bindings-12.9.11` from the chosen commit. For an emergency after a |
| 25 | +release, start from its exact tag, provided that tag contains the new package |
| 26 | +layout. For the first release after this transition, use a validated commit |
| 27 | +containing both roots. Keep routine development on `main`; the historical |
| 28 | +`12.9.x` branch stays frozen except for emergency fixes using compatible |
| 29 | +historical tooling. Reconcile those fixes into the main-tree maintenance |
| 30 | +root. Keep the package layout and release tooling together on new release branches. |
| 31 | + |
| 32 | +Record the source commit, intended tag, selected package root, release owner, |
| 33 | +and accepted changes in the release checklist. A branch is a temporary scope |
| 34 | +boundary, not a separate long-term home for shared infrastructure. |
| 35 | + |
| 36 | +## Move fixes between integration and release branches |
| 37 | + |
| 38 | +Prefer a reviewed fix on `main`, then backport it to the selected release |
| 39 | +branch in a separate PR. Inspect the diff, request CI using the normal PR |
| 40 | +approval procedure, and review it before merging. Conflicts and toolkit-specific |
| 41 | +generated changes require an explicitly reviewed adaptation. |
| 42 | + |
| 43 | +If urgency requires a fix on the release branch first, link a follow-up PR |
| 44 | +reconciling the fix back into `main` before closing the release checklist. In either |
| 45 | +direction, assess both bindings roots and record why a change applies to one |
| 46 | +or both. Regenerate affected generated files from the intended toolkit and |
| 47 | +cybind inputs instead of blindly copying generated output between majors. |
| 48 | + |
| 49 | +## Validate and publish the selected line |
| 50 | + |
| 51 | +1. Finalize the bindings and metapackage release notes, dependency constraints, |
| 52 | + and selected toolkit pin in the release source tree. The registry and |
| 53 | + packaging metadata must agree. Run the CI-tool suite and pre-commit checks. |
| 54 | +2. Test the candidate through a reviewed PR or manual CI dispatch on its |
| 55 | + branch. Normal development CI includes dependent packages and may cover |
| 56 | + both majors. Resolve failures in affected code before selecting the tag. |
| 57 | +3. Create the approved immutable `vX.Y.Z` tag at the selected source commit. |
| 58 | + Tag-triggered CI builds both bindings lines and their consumers. The release |
| 59 | + workflow selects only the requested line's bindings or metapackage artifacts. |
| 60 | + The tag does not have to be on `main`. Wait for this exact tag's CI to pass. |
| 61 | +4. Run **CI: Release** with `release-action=dry-run`, the tag, and |
| 62 | + `component=cuda-bindings`; repeat for `cuda-python`. Leave `run-id` blank |
| 63 | + to exercise automatic lookup, and leave `dry-run-docs-branch` blank to avoid |
| 64 | + deploying docs. The workflow verifies a successful tag-triggered CI run |
| 65 | + with the exact source SHA, validates artifacts, and builds docs. |
| 66 | +5. Review the dry runs, then separately approve and run `full-release` for |
| 67 | + each component under the team's release procedure. A successful candidate |
| 68 | + rehearsal or ordinary branch CI is not a substitute for exact-tag CI. |
| 69 | +6. After both component releases succeed, review and publish the shared |
| 70 | + `vX.Y.Z` GitHub Release draft. Check its release notes, versioned |
| 71 | + documentation links, source archive, checksum, and wheels. These component |
| 72 | + workflows leave the draft for the release owner to publish. |
| 73 | +7. Finish post-release QA and announcements, return every applicable fix to |
| 74 | + `main`, and close the stabilization effort. Retain immutable tags and the |
| 75 | + branch history needed for diagnosis. |
| 76 | + |
| 77 | +For either bindings line, add the released version to |
| 78 | +[`cuda_bindings_13/docs/nv-versions.json`](../cuda_bindings_13/docs/nv-versions.json) |
| 79 | +and its matching metapackage version to |
| 80 | +[`cuda_python/docs/nv-versions.json`](../cuda_python/docs/nv-versions.json) |
| 81 | +on `main`. Documentation deployments from `main` own these shared version |
| 82 | +selectors. Release deployments publish versioned pages without replacing the |
| 83 | +selectors or shared `latest` pages; updating a selector only on a stabilization |
| 84 | +branch will not update the public selector. |
| 85 | + |
| 86 | +The workflow revision used for a release is its **control revision**; the |
| 87 | +tagged commit is its **source revision**. Record both and the artifact CI run |
| 88 | +ID. Release routing uses the package layout and toolkit settings in |
| 89 | +`ci/versions.yml` at the release tag. Retained CUDA 13 tags also support the |
| 90 | +older `cuda.build.version` configuration, the `cuda_bindings` source directory, |
| 91 | +and their original build matrix and metapackage artifact name. New CUDA 12 |
| 92 | +releases require the local `cuda_bindings_12` root and toolkit-qualified |
| 93 | +artifacts. The workflow control revision never supplies missing tagged toolkit |
| 94 | +settings or replaces tagged release notes. Older CUDA 12 branch releases use |
| 95 | +their compatible historical tooling. |
| 96 | + |
| 97 | +In **CI: Release**, normal bindings and metapackage releases each require |
| 98 | +their own exact-version, nonempty release notes in the tagged source. Notes |
| 99 | +from the workflow control revision or a different component cannot fill a gap. |
| 100 | +Preserve their existing exemption for `.postN` releases, which do not require |
| 101 | +new notes. |
| 102 | + |
| 103 | +Local synthetic tags used in publication-incapable rehearsals must remain local; |
| 104 | +they do not authorize publishing a package, creating a remote tag, or moving |
| 105 | +an existing tag. |
0 commit comments