From 7e689a3dcf1caec317d41566bec630bae36ac0aa Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Fri, 20 Nov 2026 14:33:49 -0800 Subject: [PATCH 1/4] Fix documentation version-selector publication timing Signed-off-by: Ralf W. Grosse-Kunstleve --- .github/RELEASE-bindings.md | 17 +- .github/RELEASE-core.md | 31 ++- .pre-commit-config.yaml | 2 +- ci/README.md | 29 +-- ci/tools/check_staged_release_notes.py | 77 +------ .../test_check_release_note_selectors.py | 208 ------------------ .../tests/test_check_staged_release_notes.py | 15 ++ cuda_core/docs/nv-versions.json | 4 - 8 files changed, 62 insertions(+), 321 deletions(-) delete mode 100644 ci/tools/tests/test_check_release_note_selectors.py diff --git a/.github/RELEASE-bindings.md b/.github/RELEASE-bindings.md index 84b90cd901ef..b6dc53d63be7 100644 --- a/.github/RELEASE-bindings.md +++ b/.github/RELEASE-bindings.md @@ -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 diff --git a/.github/RELEASE-core.md b/.github/RELEASE-core.md index 61228659566f..3b575c0f5a44 100644 --- a/.github/RELEASE-core.md +++ b/.github/RELEASE-core.md @@ -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. --- @@ -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. @@ -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 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index d90a91fda1cc..aa1dcdf850ee 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -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 diff --git a/ci/README.md b/ci/README.md index 9c971cf9eac1..96ab7cbbdc50 100644 --- a/ci/README.md +++ b/ci/README.md @@ -342,26 +342,13 @@ 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_` 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//`, 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 +the package's `docs/nv-versions.json` on `main` only after that component is +published and its versioned documentation is deployed. 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, @@ -371,7 +358,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 diff --git a/ci/tools/check_staged_release_notes.py b/ci/tools/check_staged_release_notes.py index 8056cb26e09b..dce6c45c2686 100644 --- a/ci/tools/check_staged_release_notes.py +++ b/ci/tools/check_staged_release_notes.py @@ -1,11 +1,10 @@ # 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 @@ -13,16 +12,7 @@ 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: @@ -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, @@ -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 @@ -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 diff --git a/ci/tools/tests/test_check_release_note_selectors.py b/ci/tools/tests/test_check_release_note_selectors.py deleted file mode 100644 index baafa6253119..000000000000 --- a/ci/tools/tests/test_check_release_note_selectors.py +++ /dev/null @@ -1,208 +0,0 @@ -# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 - -from __future__ import annotations - -import json -import subprocess -from pathlib import Path - -import pytest - -from ci.tools.check_staged_release_notes import ( - _build_indexed_release_notes, - version_selector_errors, -) - -SELECTORS = ( - "cuda_python/docs/nv-versions.json", - "cuda_bindings_13/docs/nv-versions.json", - "cuda_core/docs/nv-versions.json", - "cuda_pathfinder/docs/nv-versions.json", -) - - -def git(repo: Path, *args: str) -> None: - subprocess.run( # noqa: S603 - ["git", "-C", str(repo), *args], # noqa: S607 - capture_output=True, - check=True, - ) - - -def stage_file(repo: Path, relative: str, contents: str) -> str: - path = repo / relative - path.parent.mkdir(parents=True, exist_ok=True) - path.write_text(contents, encoding="utf-8") - git(repo, "add", relative) - return relative - - -@pytest.fixture -def repo(tmp_path): - git(tmp_path, "init", "-q") - stage_file(tmp_path, "cuda_bindings_12/README.md", "Maintenance bindings root.\n") - for selector in SELECTORS: - stage_file(tmp_path, selector, "[]\n") - return tmp_path - - -@pytest.mark.parametrize( - "package,version,selector,url", - [ - ( - "cuda_bindings_12", - "12.9.11", - "cuda_bindings_13/docs/nv-versions.json", - "https://nvidia.github.io/cuda-python/cuda-bindings/12.9.11/", - ), - ( - "cuda_bindings_13", - "13.5.1", - "cuda_bindings_13/docs/nv-versions.json", - "https://nvidia.github.io/cuda-python/cuda-bindings/13.5.1/", - ), - ( - "cuda_python", - "12.9.11", - "cuda_python/docs/nv-versions.json", - "https://nvidia.github.io/cuda-python/12.9.11/", - ), - ( - "cuda_core", - "1.3.2", - "cuda_core/docs/nv-versions.json", - "https://nvidia.github.io/cuda-python/cuda-core/1.3.2/", - ), - ( - "cuda_pathfinder", - "1.9.2", - "cuda_pathfinder/docs/nv-versions.json", - "https://nvidia.github.io/cuda-python/cuda-pathfinder/1.9.2/", - ), - ], -) -@pytest.mark.agent_authored(model="gpt-6") -def test_release_notes_require_their_version_and_exact_url_in_the_correct_selector( - repo, package, version, selector, url -): - note = stage_file(repo, f"{package}/docs/source/release/{version}-notes.rst", "Release notes.\n") - - for entries in ([], [{"version": version, "url": url.removesuffix("/")}]): - stage_file(repo, selector, json.dumps(entries)) - errors = version_selector_errors(repo, _build_indexed_release_notes(repo)) - assert len(errors) == 1 - assert all(value in errors[0] for value in (note, version, selector)) - - stage_file(repo, selector, json.dumps([{"version": version, "url": url}])) - assert version_selector_errors(repo, _build_indexed_release_notes(repo)) == [] - - -@pytest.mark.parametrize( - "package,version", - [ - ("cuda_bindings_12", "12.9.10"), - ("cuda_bindings_13", "13.5.0"), - ("cuda_python", "12.9.10"), - ("cuda_python", "13.5.0"), - ("cuda_core", "1.3.1"), - ("cuda_pathfinder", "1.9.1"), - ], -) -@pytest.mark.agent_authored(model="gpt-6") -def test_pre_policy_release_notes_do_not_require_selector_entries(repo, package, version): - stage_file(repo, f"{package}/docs/source/release/{version}-notes.rst", "Release notes.\n") - - assert version_selector_errors(repo, _build_indexed_release_notes(repo)) == [] - - -@pytest.mark.agent_authored(model="gpt-6") -def test_unstaged_json_correction_does_not_replace_the_staged_selector(repo): - selector = "cuda_core/docs/nv-versions.json" - stage_file(repo, "cuda_core/docs/source/release/1.3.2-notes.rst", "Release notes.\n") - stage_file( - repo, - selector, - json.dumps([{"version": "1.3.2", "url": "https://nvidia.github.io/cuda-python/cuda-core/latest/"}]), - ) - staged_errors = version_selector_errors(repo, _build_indexed_release_notes(repo)) - assert len(staged_errors) == 1 - (repo / selector).write_text( - json.dumps([{"version": "1.3.2", "url": "https://nvidia.github.io/cuda-python/cuda-core/1.3.2/"}]), - encoding="utf-8", - ) - - assert version_selector_errors(repo, _build_indexed_release_notes(repo)) == staged_errors - - git(repo, "add", selector) - assert version_selector_errors(repo, _build_indexed_release_notes(repo)) == [] - - -@pytest.mark.agent_authored(model="gpt-6") -def test_staged_selector_deletion_fails_even_without_release_notes(repo): - selector = "cuda_core/docs/nv-versions.json" - git(repo, "rm", "--cached", selector) - assert (repo / selector).is_file() - - with pytest.raises(subprocess.CalledProcessError): - version_selector_errors(repo, _build_indexed_release_notes(repo)) - - -@pytest.mark.agent_authored(model="GPT-6") -def test_unreleased_bindings_root_keeps_the_current_selector_for_maintenance_notes(repo): - entries = [{"version": "13.5.1", "url": "https://nvidia.github.io/cuda-python/cuda-bindings/13.5.1/"}] - stage_file(repo, "cuda_bindings_13/docs/source/release/13.5.1-notes.rst", "Release notes.\n") - stage_file(repo, "cuda_bindings_13/docs/nv-versions.json", json.dumps(entries)) - stage_file(repo, "cuda_bindings_14/docs/source/release/14.X.Y-notes.rst", "Future release template.\n") - - assert version_selector_errors(repo, _build_indexed_release_notes(repo)) == [] - - selector = "cuda_bindings_13/docs/nv-versions.json" - note = stage_file(repo, "cuda_bindings_12/docs/source/release/12.9.11-notes.rst", "Release notes.\n") - errors = version_selector_errors(repo, _build_indexed_release_notes(repo)) - assert len(errors) == 1 - assert all(value in errors[0] for value in (note, "12.9.11", selector)) - - entries.append({"version": "12.9.11", "url": "https://nvidia.github.io/cuda-python/cuda-bindings/12.9.11/"}) - stage_file(repo, selector, json.dumps(entries)) - assert version_selector_errors(repo, _build_indexed_release_notes(repo)) == [] - - -@pytest.mark.agent_authored(model="GPT-6") -def test_retiring_the_oldest_staged_bindings_root_advances_selector_ownership(repo): - entries = [{"version": "13.5.1", "url": "https://nvidia.github.io/cuda-python/cuda-bindings/13.5.1/"}] - note = stage_file(repo, "cuda_bindings_13/docs/source/release/13.5.1-notes.rst", "Release notes.\n") - stage_file(repo, "cuda_bindings_13/docs/nv-versions.json", json.dumps(entries)) - stage_file(repo, "cuda_bindings_14/docs/source/release/14.X.Y-notes.rst", "Future release template.\n") - assert version_selector_errors(repo, _build_indexed_release_notes(repo)) == [] - - git(repo, "rm", "--cached", "-r", "cuda_bindings_12") - assert (repo / "cuda_bindings_12/README.md").is_file() - with pytest.raises(subprocess.CalledProcessError): - version_selector_errors(repo, _build_indexed_release_notes(repo)) - - selector = "cuda_bindings_14/docs/nv-versions.json" - stage_file(repo, selector, "[]\n") - errors = version_selector_errors(repo, _build_indexed_release_notes(repo)) - assert len(errors) == 1 - assert all(value in errors[0] for value in (note, "13.5.1", selector)) - - stage_file(repo, selector, json.dumps(entries)) - assert version_selector_errors(repo, _build_indexed_release_notes(repo)) == [] - - -@pytest.mark.agent_authored(model="GPT-6") -def test_canonical_bindings_root_uses_numeric_major_order(repo): - entries = [{"version": "13.5.1", "url": "https://nvidia.github.io/cuda-python/cuda-bindings/13.5.1/"}] - stage_file(repo, "cuda_bindings_9/README.md", "Older bindings root.\n") - note = stage_file(repo, "cuda_bindings_13/docs/source/release/13.5.1-notes.rst", "Release notes.\n") - stage_file(repo, "cuda_bindings_13/docs/nv-versions.json", json.dumps(entries)) - selector = "cuda_bindings_12/docs/nv-versions.json" - stage_file(repo, selector, "[]\n") - - errors = version_selector_errors(repo, _build_indexed_release_notes(repo)) - assert len(errors) == 1 - assert all(value in errors[0] for value in (note, "13.5.1", selector)) - - stage_file(repo, selector, json.dumps(entries)) - assert version_selector_errors(repo, _build_indexed_release_notes(repo)) == [] diff --git a/ci/tools/tests/test_check_staged_release_notes.py b/ci/tools/tests/test_check_staged_release_notes.py index 6b338d2e8683..a2f3d798b6a2 100644 --- a/ci/tools/tests/test_check_staged_release_notes.py +++ b/ci/tools/tests/test_check_staged_release_notes.py @@ -8,6 +8,7 @@ import pytest +from ci.tools import check_staged_release_notes from ci.tools.check_staged_release_notes import ( _build_indexed_release_notes, missing_release_note_pairs, @@ -36,6 +37,20 @@ def write_note(repo: Path, package: str, version: str) -> str: return relative +@pytest.mark.agent_authored(model="gpt-6") +def test_upcoming_release_notes_do_not_require_advertising_versions(repo, monkeypatch): + for package, version in [ + ("cuda_core", "1.4.0"), + ("cuda_pathfinder", "1.9.2"), + ("cuda_bindings_13", "13.5.1"), + ("cuda_python", "13.5.1"), + ]: + git(repo, "add", write_note(repo, package, version)) + monkeypatch.setattr(check_staged_release_notes, "ROOT", repo) + + assert check_staged_release_notes.main() == 0 + + @pytest.mark.parametrize( "package,version", [ diff --git a/cuda_core/docs/nv-versions.json b/cuda_core/docs/nv-versions.json index 6331b7d0ccd3..5f3975fc5144 100644 --- a/cuda_core/docs/nv-versions.json +++ b/cuda_core/docs/nv-versions.json @@ -3,10 +3,6 @@ "version": "latest", "url": "https://nvidia.github.io/cuda-python/cuda-core/latest/" }, - { - "version": "1.4.0", - "url": "https://nvidia.github.io/cuda-python/cuda-core/1.4.0/" - }, { "version": "1.3.1", "url": "https://nvidia.github.io/cuda-python/cuda-core/1.3.1/" From ae5f0ec0b9b1761b7526d802ffe78369341d33bb Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Fri, 20 Nov 2026 14:33:54 -0800 Subject: [PATCH 2/4] ci: require manual copy-pr-bot approval From 9302bf8283da840e9f127d0a59a46fedd8bb2560 Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Fri, 20 Nov 2026 14:44:04 -0800 Subject: [PATCH 3/4] Clarify the shared bindings selector and trim redundant test Signed-off-by: Ralf W. Grosse-Kunstleve --- ci/README.md | 8 +++++--- ci/tools/tests/test_check_staged_release_notes.py | 15 --------------- 2 files changed, 5 insertions(+), 18 deletions(-) diff --git a/ci/README.md b/ci/README.md index 96ab7cbbdc50..a928e6cf749b 100644 --- a/ci/README.md +++ b/ci/README.md @@ -345,9 +345,11 @@ before publication. 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 -the package's `docs/nv-versions.json` on `main` only after that component is -published and its versioned documentation is deployed. Deployments from `main` -own these shared selectors; release deployments leave them unchanged. A missing +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 diff --git a/ci/tools/tests/test_check_staged_release_notes.py b/ci/tools/tests/test_check_staged_release_notes.py index a2f3d798b6a2..6b338d2e8683 100644 --- a/ci/tools/tests/test_check_staged_release_notes.py +++ b/ci/tools/tests/test_check_staged_release_notes.py @@ -8,7 +8,6 @@ import pytest -from ci.tools import check_staged_release_notes from ci.tools.check_staged_release_notes import ( _build_indexed_release_notes, missing_release_note_pairs, @@ -37,20 +36,6 @@ def write_note(repo: Path, package: str, version: str) -> str: return relative -@pytest.mark.agent_authored(model="gpt-6") -def test_upcoming_release_notes_do_not_require_advertising_versions(repo, monkeypatch): - for package, version in [ - ("cuda_core", "1.4.0"), - ("cuda_pathfinder", "1.9.2"), - ("cuda_bindings_13", "13.5.1"), - ("cuda_python", "13.5.1"), - ]: - git(repo, "add", write_note(repo, package, version)) - monkeypatch.setattr(check_staged_release_notes, "ROOT", repo) - - assert check_staged_release_notes.main() == 0 - - @pytest.mark.parametrize( "package,version", [ From 34dbaaa32075fb4022f1bd530ba7b7678225a815 Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Fri, 20 Nov 2026 17:58:19 -0800 Subject: [PATCH 4/4] docs: clarify when to update documentation version selectors Signed-off-by: Ralf W. Grosse-Kunstleve --- cuda_bindings_12/docs/README.md | 12 ++++++++---- cuda_bindings_13/docs/README.md | 10 +++++++--- cuda_core/docs/README.md | 10 +++++++--- cuda_pathfinder/docs/README.md | 10 +++++++--- cuda_python/docs/README.md | 14 +++++++++----- 5 files changed, 38 insertions(+), 18 deletions(-) diff --git a/cuda_bindings_12/docs/README.md b/cuda_bindings_12/docs/README.md index b533f56e3492..6156eadc6c02 100644 --- a/cuda_bindings_12/docs/README.md +++ b/cuda_bindings_12/docs/README.md @@ -6,10 +6,14 @@ The aggregate `cuda_python/docs/build_all_docs.sh` script builds the current CUDA 13 line, so build this maintenance documentation separately. 1. Install the CUDA 12 `cuda-bindings` build that you need to document. -2. Ensure the version is included in the canonical - [`nv-versions.json`](../../cuda_bindings_13/docs/nv-versions.json). -3. Build the docs with `./build_docs.sh`. -4. The html artifacts should be available under both `./build/html/latest` and `./build/html/`. +2. Build the docs with `./build_docs.sh`. +3. The html artifacts should be available under both `./build/html/latest` and + `./build/html/`. + +A local build does not require a version-selector entry. Add the version to the +canonical [`nv-versions.json`](../../cuda_bindings_13/docs/nv-versions.json) +on `main` only after the package is published and its versioned documentation +is deployed. The Pixi `docs` environment currently installs a published `12.9.*` package. To document APIs changed in the checkout, install the matching source build diff --git a/cuda_bindings_13/docs/README.md b/cuda_bindings_13/docs/README.md index c0311407c28c..684761e72ec4 100644 --- a/cuda_bindings_13/docs/README.md +++ b/cuda_bindings_13/docs/README.md @@ -1,9 +1,13 @@ # Build the documentation 1. Install the CUDA 13 `cuda-bindings` build that you need to document. -2. Ensure the version is included in the [`nv-versions.json`](./nv-versions.json). -3. Build the docs with `./build_docs.sh`. -4. The html artifacts should be available under both `./build/html/latest` and `./build/html/`. +2. Build the docs with `./build_docs.sh`. +3. The html artifacts should be available under both `./build/html/latest` and + `./build/html/`. + +A local build does not require a version-selector entry. Add the version to +[`nv-versions.json`](./nv-versions.json) on `main` only after the package is +published and its versioned documentation is deployed. [`cuda_python/docs/build_all_docs.sh`](../../cuda_python/docs/build_all_docs.sh) builds this current bindings line together with the metapackage, Core, and diff --git a/cuda_core/docs/README.md b/cuda_core/docs/README.md index aae9ebf98525..613fad8376f8 100644 --- a/cuda_core/docs/README.md +++ b/cuda_core/docs/README.md @@ -1,9 +1,13 @@ # Build the documentation 1. Install the `cuda-core` package of the version that we need to document. -2. Ensure the version is included in the [`nv-versions.json`](./nv-versions.json). -3. Build the docs with `./build_docs.sh`. -4. The html artifacts should be available under both `./build/html/latest` and `./build/html/`. +2. Build the docs with `./build_docs.sh`. +3. The html artifacts should be available under both `./build/html/latest` and + `./build/html/`. + +A local build does not require a version-selector entry. Add the version to +[`nv-versions.json`](./nv-versions.json) on `main` only after the package is +published and its versioned documentation is deployed. For local development, `cuda_core/pixi.toml` now includes a dedicated `docs` environment that mirrors the CI Sphinx dependencies: diff --git a/cuda_pathfinder/docs/README.md b/cuda_pathfinder/docs/README.md index 47b62fc67710..71bdd6eb5b30 100644 --- a/cuda_pathfinder/docs/README.md +++ b/cuda_pathfinder/docs/README.md @@ -1,9 +1,13 @@ # Build the documentation 1. Install the `cuda-pathfinder` package of the version that we need to document. -2. Ensure the version is included in the [`nv-versions.json`](./nv-versions.json). -3. Build the docs with `./build_docs.sh`. -4. The html artifacts should be available under both `./build/html/latest` and `./build/html/`. +2. Build the docs with `./build_docs.sh`. +3. The html artifacts should be available under both `./build/html/latest` and + `./build/html/`. + +A local build does not require a version-selector entry. Add the version to +[`nv-versions.json`](./nv-versions.json) on `main` only after the package is +published and its versioned documentation is deployed. Alternatively, we can build all the docs at once by running [`cuda_python/docs/build_all_docs.sh`](../../cuda_python/docs/build_all_docs.sh). diff --git a/cuda_python/docs/README.md b/cuda_python/docs/README.md index 76b46c7d0613..a308779d52d1 100644 --- a/cuda_python/docs/README.md +++ b/cuda_python/docs/README.md @@ -1,8 +1,12 @@ # Build the documentation -1. Ensure the version is included in the [`versions.json`](./versions.json). -2. Build the docs with `./build_docs.sh`. -3. The html artifacts should be available under both `./build/html/latest` and `./build/html/`. +1. Build the docs with `./build_docs.sh`. +2. The html artifacts should be available under both `./build/html/latest` and + `./build/html/`. + +A local build does not require a version-selector entry. Add the version to +[`nv-versions.json`](./nv-versions.json) on `main` only after the package is +published and its versioned documentation is deployed. [`./build_all_docs.sh`](./build_all_docs.sh) builds the metapackage, current CUDA 13 bindings, Core, and Pathfinder documentation together. It does not @@ -23,5 +27,5 @@ ssh -L 1234:localhost:1234 username@hostname ``` Then browse the built docs by visiting `http://localhost:1234/` on a local machine. -To publish the docs with the built version, it is important to note that the html files of older versions -should be kept intact, in order for the version selection (through `versions.json`) to work. +Keep older versioned HTML pages intact so existing version-selector entries +continue to work.