[rwgk]

— codex GPT-6 on behalf of Ralf —

Layer 5 of 7 of the staged "CUDA 12 bindings on main" stack. Previous: #3318. Next: #3321. Stack map at the bottom.

What this PR does

Makes git tag v12.9.N on main (or on a release branch) a complete release path, while CUDA 13 releases keep working exactly as today.

The one idea to hold on to: a release reads its configuration from the tagged source, not from the workflow revision. A new resolve-bindings-package job checks out the tag into release-source/, reads its ci/versions.yml, and decides the package root and toolkit (cuda_bindings_12 / 12.9.1 for v12.9.*). Retained CUDA 13 tags with the old cuda.build.version format and the old cuda_bindings/ directory are recognized too, so a v13.4.4 dry run still works from main's workflow.

Everything else follows from that:

• Artifacts get toolkit-qualified names everywhere: cuda-bindings-python<py>-cuda<toolkit>-<platform>-<sha> for both roots and cuda-python-wheel-cuda<toolkit> for both metapackages. The temporary maintenance-* names from ci: build and test local CUDA 12 bindings #3317/ci: use same-run CUDA 12 bindings for Core and metapackages #3318 are gone. The old cuda-python-wheel alias is still uploaded for older consumers (removed in ci: retire legacy branch-based bindings maintenance #3322).
• ci/tools/download-wheels selects artifacts by toolkit, inspects artifact names before downloading, and can no longer pick up *-tests artifacts (a hazard Keith flagged on cuda.bindings: support multiple CTK release lines on main #2737). Dependent Core/Pathfinder tag documentation selects one metapackage using the resolved bindings toolkit.
• ci/tools/validate_release_wheels.py (new; replaces the shell wrapper) checks the complete wheel matrix (Python versions x platforms, read from the tagged source) and rejects dev/local versions and duplicates.
• ci/tools/check_release_notes.py drops the backport_branch logic. Notes must exist for the exact version in the tagged source; .postN releases are exempt; Pathfinder keeps its own rule.
• ci/tools/lookup-run-id --run-id validates a supplied run ID (same tag, same SHA, successful push run) instead of trusting it.
• build-docs.yml: a .ci-control checkout supplies the tooling, the release source supplies package data; CUDA 13 docs are built against the checkout's bindings (pixi docs feature uses path = "."); build_docs.sh keeps .dev and rc versions in their own directory so they cannot overwrite stable pages.
• ci.yml: a bare v* tag run builds the bindings docs only.
• RELEASE-bindings.md (new), RELEASE-core.md, and the release checklist describe the procedure.

After this merges

• v13.4.N: unchanged procedure.
• v12.9.N on main: tag CI builds both lines (per-line selection arrives with ci: plan builds and artifact reuse per bindings root #3321); CI: Release with component cuda-bindings, then cuda-python, publishes the CUDA 12 line.
• The bindings and metapackage artifact names change for every consumer in the repository; the old metapackage name survives as an alias until ci: retire legacy branch-based bindings maintenance #3322.

Where to look

• .github/workflows/release.yml: resolve-bindings-package, determine-run-id, and how the resolved package flows into docs, upload, and publish jobs.
• ci/tools/bindings_config.py: resolve_release_bindings_package(), including the retained-CUDA-13 branch.
• ci/tools/download-wheels and ci/tools/validate_release_wheels.py: what can reach PyPI.
• .github/RELEASE-bindings.md: the operator's view.

All changes (29 files; 28 without the lockfile, +1,893 / -821)

Workflows: release.yml, release-upload.yml, build-docs.yml, build-wheel.yml (artifact names), ci.yml (docs component on tags), test-sdist-*.yml and test-wheel-*.yml (artifact names), .pre-commit-config.yaml (hook dependency).

Tools: bindings_config.py (tag matching, release resolution, write-github-env), check_release_notes.py, download-wheels, lookup-run-id, validate_release_wheels.py (new), validate-release-wheels (deleted), env-vars.

Tests: test_bindings_release_compat.py (new), test_download_wheels.py (new), test_validate_release_wheels.py (new), test_check_release_notes.py (rewritten for the new policy).

Docs and environments: .github/RELEASE-bindings.md (new), RELEASE-core.md, ISSUE_TEMPLATE/release_checklist.yml, cuda_bindings_13/docs/build_docs.sh, cuda_bindings_13/pixi.toml + lock (docs feature builds from source), cuda_python/docs/environment-docs.yml, toolshed/setup-docs-env.sh (furo for the CUDA 12 docs theme).

Validation and what has not been exercised

• Full CI passed at the pre-rebase head 6600f4cd (run 41194257043, 106 jobs).
• Unit tests cover tag resolution for schema-2 and legacy sources, artifact selection by toolkit, test-artifact exclusion, the complete-matrix check, and the notes policy.
• Not exercised: a real tag-triggered CI run and a CI: Release dry run with this workflow. A dry run for an existing tag (for example v13.4.4) from the merged main is the natural first check.
• Current head 1bfdf64400ae73f84d064bcb7c849480c98395be includes the follow-up fixes. Local validation: 327 CI-tool tests, actionlint passed. Full CI and native Pixi source/GPU checks have not been rerun for it.

Stack map: what main can do after each layer merges

Layer	PR	After it merges, main ...
1	#3314	behaves exactly as before; CI has one reader for the two bindings roots; CUDA 13 versions can no longer match a v12.* tag
2	#3315	lets a developer build, test, and document cuda_bindings_12/; the PR-time CPU source-build smoke covers both roots; three CUDA 12 runtime fixes are in
3	#3317	builds the CUDA 12 bindings wheel itself and runs its GPU tests; cuda.core and the metapackage still consume 12.9.x artifacts
4	#3318	uses same-run CUDA 12 wheels everywhere; PR CI no longer reads the 12.9.x branch
5	#3319	can release CUDA 12 from a v12.9.N tag on main; CUDA 13 releases are unchanged
6	#3321	builds and tests only what a change needs, per bindings root, reusing baseline artifacts
7	#3322	carries the schema-2 registry, a manual-only backport workflow, a metadata consistency hook, and the maintenance docs; 12.9.x is frozen

Every layer was designed to be mergeable on its own and had a green full CI run at its pre-rebase head on 2026-10-31. The stack is the "individually mergeable pieces" alternative to #3174-#3182; both stacks reach the same end state except that this one keeps compatibility routes for older artifact sources and retained CUDA 13 tags.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[rwgk]

/ok to test 6600f4c

[github-actions]

Doc Preview CI
🚀 View preview at https://nvidia.github.io/cuda-python/pr-preview/pr-3319/
https://nvidia.github.io/cuda-python/pr-preview/pr-3319/cuda-core/
https://nvidia.github.io/cuda-python/pr-preview/pr-3319/cuda-bindings/
https://nvidia.github.io/cuda-python/pr-preview/pr-3319/cuda-pathfinder/
Preview will be ready when the GitHub Pages deployment is complete.