Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 12 additions & 5 deletions .github/RELEASE-bindings.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,13 +71,20 @@ release dry run. Tag CI does not publish documentation. This focused tag-CI
check is specific to the shared bindings/metapackage tags; Core and Pathfinder
release behavior is unchanged.

For either bindings line, add the released version to
Release notes can land on `main` before publication without entries in the
documentation version selectors. For either bindings line, wait for successful
publication and deployment of each component's versioned documentation, then
open a PR on `main` adding the released bindings version to
[`cuda_bindings_13/docs/nv-versions.json`](../cuda_bindings_13/docs/nv-versions.json)
and its matching metapackage version to
[`cuda_python/docs/nv-versions.json`](../cuda_python/docs/nv-versions.json)
on `main`. Documentation deployments from `main` own these shared version
selectors. Release deployments publish versioned pages without replacing the
selectors or shared `latest` pages.
[`cuda_python/docs/nv-versions.json`](../cuda_python/docs/nv-versions.json).
Confirm that each versioned documentation URL works before merging its entry.

Documentation deployments from `main` own these shared version selectors.
Release deployments publish versioned pages without replacing the selectors or
shared `latest` pages. An entry in the tagged source alone does not update the
live switcher. If an entry is missing after release, correct it on `main`
without changing the release tag.

The workflow revision used for a release is its **control revision**; the
tagged commit is its **source revision**. Record both and the artifact CI run
Expand Down
31 changes: 20 additions & 11 deletions .github/RELEASE-core.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,15 +145,9 @@ entries for length, specificity, tone, and consistency. Highlight a few
notable items in the highlights section, keeping their full entries in the
appropriate sections below.

---

## Update the docs for the new version

Add the new version to
`cuda_core/docs/nv-versions.json`. This file drives the version
switcher on the documentation site. Add an entry for the new version
after `"latest"`, following the existing pattern. The docs themselves are
built and deployed automatically by the release workflow.
Numeric release notes can land on `main` before publication. They do not require
an entry in the documentation version switcher: adding an unreleased version
would advertise documentation that is not deployed yet.

---

Expand All @@ -176,8 +170,8 @@ For a patch release (`X.Y.Z`), use the existing branch. Changes reach it
through pull requests that cherry-pick the fixes from `main`, with
`(cherry picked from commit ...)` trailers. The release notes for the patch
release must be on the release branch before the tag: the release workflow
checks for them in the tagged tree. Add them to `main` as well, so the docs
switcher and the `latest` docs list them.
checks for them in the tagged tree. Add them to `main` as well, so the `latest`
docs include them.

The repository ruleset protects `release/**`: a push to an existing release
branch needs a pull request and passing checks.
Expand Down Expand Up @@ -247,6 +241,21 @@ pip install cuda-core==0.6.0

---

## Update the docs for the new version

After publication succeeds and the versioned documentation is deployed, open a
PR on `main` adding the new version to `cuda_core/docs/nv-versions.json` after
`"latest"`, following the existing pattern. Confirm that the versioned
documentation URL works before merging the entry.

This file drives the shared version switcher used by existing documentation
pages. Deployments from `main` publish it; release deployments publish versioned
pages without replacing the selector or shared `latest` pages. An entry in the
tagged source alone does not update the live switcher. If an entry is missing
after release, correct it on `main` without changing the release tag.

---

## Update the conda recipe & release conda packages

The conda-forge feedstock builds from the GitHub Release source archive
Expand Down
2 changes: 1 addition & 1 deletion .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ repos:
pass_filenames: false

- id: check-staged-release-notes
name: Check staged release-note pairs and documentation version selectors
name: Check staged release-note pairs
entry: python -m ci.tools.check_staged_release_notes
language: python
always_run: true
Expand Down
31 changes: 10 additions & 21 deletions ci/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -342,26 +342,15 @@ and during `pre-commit run --all-files`.
The tagged-source checks in the release workflow remain the final validation
before publication.

The same hook checks documentation version selectors for these bindings and
metapackage releases, Core releases starting at **1.3.2**, and Pathfinder
releases starting at **1.9.2**. Each checked numeric release note must have its
version listed in the package's `docs/nv-versions.json`, with the exact
versioned documentation URL, including the trailing slash. All bindings roots
share the selector in the second root after sorting indexed
`cuda_bindings_<major>` roots in ascending numeric order. Exactly two or three
roots are expected: maintenance, current, and optionally a newer unreleased
major. Both `[12, 13]` and `[12, 13, 14]` therefore use
`cuda_bindings_13/docs/nv-versions.json`. Retiring root 12 leaves `[13, 14]`
and moves ownership to `cuda_bindings_14/docs/nv-versions.json`; stage that
selector and coordinate the build and release routing migration. Discovery
uses all indexed files, including templates, before applying note cutoffs.
The hook does not fall back to another root. Metapackage URLs use
`https://nvidia.github.io/cuda-python/<version>/`, while the other components
use their `cuda-bindings`, `cuda-core`, or `cuda-pathfinder` subdirectory.

The hook uses only the standard library. All four selectors must exist in
Git's index and parse as JSON. The hook reads their staged contents, so
unstaged edits cannot satisfy the check.
The hook uses only the standard library and checks note pairing independently
of documentation version selectors. Numeric release notes can describe work
for an upcoming release without advertising unpublished documentation. Update
selectors on `main` only after the component is published and its versioned
documentation is deployed. Both bindings majors use
`cuda_bindings_13/docs/nv-versions.json`; the metapackage, Core, and Pathfinder
use their own package's `docs/nv-versions.json`. Deployments from `main` own
these shared selectors; release deployments leave them unchanged. A missing
selector entry can be corrected on `main` without changing the release tag.

Tag-push CI runs the `--tag-ci` mode of
`ci/tools/check_tagged_release_notes.py` at the start of its `should-skip` job,
Expand All @@ -371,7 +360,7 @@ bindings major; `cuda-core-v` and `cuda-pathfinder-v` tags select their own
component. Public beta, release-candidate, and final tags require their full
version in the filename. Internal alpha and development tags skip this check.
Post releases require a new note only for Pathfinder. This early check tests
file existence; pairing and selectors belong to the separate staged check.
file existence; pairing belongs to the separate staged check.

The same module provides the publication preflight used by the release
workflow. Publication mode checks the requested component in the tagged
Expand Down
77 changes: 6 additions & 71 deletions ci/tools/check_staged_release_notes.py
Original file line number Diff line number Diff line change
@@ -1,28 +1,18 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

"""Check release-note pairing and documentation version selectors."""
"""Check staged bindings and metapackage release-note pairs."""

from __future__ import annotations

import json
import re
import subprocess
import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parents[2]
METAPACKAGE_NOTES = "cuda_python/docs/source/release"
RELEASE_NOTE = re.compile(
r"(cuda_bindings_[^/]+|cuda_python|cuda_core|cuda_pathfinder)"
r"/docs/source/release/([0-9]+\.[0-9]+\.[0-9]+)-notes\.rst"
)
SELECTOR_URLS = {
"cuda_python": "https://nvidia.github.io/cuda-python/",
"cuda_core": "https://nvidia.github.io/cuda-python/cuda-core/",
"cuda_pathfinder": "https://nvidia.github.io/cuda-python/cuda-pathfinder/",
"cuda_bindings": "https://nvidia.github.io/cuda-python/cuda-bindings/",
}
RELEASE_NOTE = re.compile(r"(cuda_bindings_[^/]+|cuda_python)/docs/source/release/([0-9]+\.[0-9]+\.[0-9]+)-notes\.rst")


def _requires_pairing(version: str) -> bool:
Expand All @@ -41,8 +31,6 @@ def _build_indexed_release_notes(repo_root: Path) -> dict[str, tuple[str, str]]:
"--",
"cuda_bindings_*/docs/source/release/*-notes.rst",
f"{METAPACKAGE_NOTES}/*-notes.rst",
"cuda_core/docs/source/release/*-notes.rst",
"cuda_pathfinder/docs/source/release/*-notes.rst",
],
cwd=repo_root,
stdout=subprocess.PIPE,
Expand All @@ -53,13 +41,7 @@ def _build_indexed_release_notes(repo_root: Path) -> dict[str, tuple[str, str]]:
for path in listing.split("\0"):
if match := RELEASE_NOTE.fullmatch(path):
package, version = match.groups()
if package == "cuda_core":
required = tuple(map(int, version.split("."))) >= (1, 3, 2)
elif package == "cuda_pathfinder":
required = tuple(map(int, version.split("."))) >= (1, 9, 2)
else:
required = _requires_pairing(version)
if required:
if _requires_pairing(version):
indexed_release_notes[path] = package, version
return indexed_release_notes

Expand All @@ -82,64 +64,17 @@ def missing_release_note_pairs(indexed_release_notes: dict[str, tuple[str, str]]
return sorted(missing)


def _bindings_selector_package(repo_root: Path) -> str:
listing = subprocess.run(
["git", "ls-files", "-z", "--", "cuda_bindings_*/*"], # noqa: S607
cwd=repo_root,
stdout=subprocess.PIPE,
check=True,
encoding="utf-8",
).stdout
packages = {path.split("/", 1)[0] for path in listing.split("\0") if path}
ordered_packages = sorted(packages, key=lambda package: int(package.removeprefix("cuda_bindings_")))
# Expect roots for maintenance, current, and optionally a newer unreleased major.
# Fail on an unexpected count to avoid silently choosing the wrong selector.
assert len(ordered_packages) in (2, 3), f"Expected two or three bindings roots, found {ordered_packages}"
return ordered_packages[1]


def version_selector_errors(repo_root: Path, indexed_release_notes: dict[str, tuple[str, str]]) -> list[str]:
"""Require matching versions and documentation URLs in the staged selectors."""
bindings_selector = _bindings_selector_package(repo_root)
selector_urls = {
bindings_selector if package == "cuda_bindings" else package: url for package, url in SELECTOR_URLS.items()
}
selectors: dict[str, dict[str, str]] = {}
for package in selector_urls:
path = f"{package}/docs/nv-versions.json"
contents = subprocess.run( # noqa: S603
["git", "show", f":{path}"], # noqa: S607
cwd=repo_root,
stdout=subprocess.PIPE,
check=True,
encoding="utf-8",
).stdout
selectors[package] = {entry["version"]: entry["url"] for entry in json.loads(contents)}

errors = []
for note, (package, version) in sorted(indexed_release_notes.items()):
selector_package = bindings_selector if package.startswith("cuda_bindings_") else package
path = f"{selector_package}/docs/nv-versions.json"
entries = selectors[selector_package]
expected_url = f"{selector_urls[selector_package]}{version}/"
if version not in entries:
errors.append(f"{path}: missing version {version} (required by {note})")
elif entries[version] != expected_url:
errors.append(f"{path}: version {version} URL is {entries[version]!r}; expected {expected_url!r} ({note})")
return errors


def main() -> int:
"""Report missing release-note pairs and incorrect staged version selectors."""
"""Report missing release-note pairs in the Git index."""
indexed_release_notes = _build_indexed_release_notes(ROOT)
errors = missing_release_note_pairs(indexed_release_notes) + version_selector_errors(ROOT, indexed_release_notes)
errors = missing_release_note_pairs(indexed_release_notes)
if not errors:
return 0

print("Release-note checks failed in the Git index:", file=sys.stderr)
for error in errors:
print(f" - {error}", file=sys.stderr)
print("Add and stage matching release notes and documentation version entries.", file=sys.stderr)
print("Add and stage matching cuda-bindings and cuda-python release notes.", file=sys.stderr)
return 1


Expand Down
Loading
Loading