Skip to content
Open
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
13 changes: 13 additions & 0 deletions .github/workflows/build-docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -383,6 +383,19 @@ jobs:
# Full CI's pull-request/N mirror supplies the PR number.
pr-number: ${{ env.PR_NUMBER }}

- name: Check rendered release notes
if: ${{ inputs.is-release }}
shell: bash --noprofile --norc -euo pipefail {0}
env:
RELEASE_TAG: ${{ inputs.git-tag }}
DOCS_COMPONENT: ${{ inputs.component }}
run: |
cd .ci-control
python3 -m ci.tools.check_tagged_release_notes \
--git-tag "$RELEASE_TAG" --component "$DOCS_COMPONENT" \
--repo-root .. --rendered-docs ../artifacts/docs \
--bindings-package "$RESOLVED_BINDINGS_PACKAGE"

- name: Upload docs GitHub Pages artifact
if: ${{ inputs.deploy-docs }}
uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
Expand Down
95 changes: 82 additions & 13 deletions ci/tools/check_tagged_release_notes.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
Usage:
python -m ci.tools.check_tagged_release_notes --git-tag <tag> --component <component>
python -m ci.tools.check_tagged_release_notes --tag-ci --git-tag <tag>
python -m ci.tools.check_tagged_release_notes --git-tag <tag> --component <component> --rendered-docs <staging-dir>

Each normal release requires nonempty notes for its exact version and component
in the tagged source checkout. Post releases do not require new notes, except
Expand All @@ -15,6 +16,10 @@
exists. It skips internal alpha/development tags and, except for Pathfinder,
post releases. It runs before CI sets up Python dependencies.

The --rendered-docs mode also checks that the versioned staging tree contains
the notes HTML and that its release index links to it. It skips internal tags
and empty Pathfinder placeholders, which need no rendered notes page.

Successful publication checks append the parsed version to GITHUB_OUTPUT when it is set.

Exit codes:
Expand All @@ -31,6 +36,7 @@
import re
import sys
from collections.abc import Mapping
from html.parser import HTMLParser
from pathlib import Path
from typing import TYPE_CHECKING

Expand Down Expand Up @@ -115,17 +121,27 @@ def notes_path(package: str, version: str) -> Path:
return Path(package, "docs", "source", "release", f"{version}-notes.rst")


def _component_for_tag_ci(git_tag: str) -> str:
for component in ("cuda-core", "cuda-pathfinder"):
_, prefix = COMPONENTS[component]
if git_tag.startswith(prefix):
return component
return "cuda-bindings"


def _is_internal_version(version: str) -> bool:
return re.search(r"(?:a|\.dev)\d", version) is not None


def _check_tag_ci(git_tag: str, repo_root: Path) -> int:
"""Check one notes file for the tag namespaces selected by ci.yml."""
for package, prefix in (COMPONENTS["cuda-core"], COMPONENTS["cuda-pathfinder"]):
if git_tag.startswith(prefix):
version = git_tag.removeprefix(prefix)
break
else:
version = git_tag.removeprefix("v")
component = _component_for_tag_ci(git_tag)
package, prefix = COMPONENTS[component]
version = git_tag.removeprefix(prefix)
if component == "cuda-bindings":
package = f"cuda_bindings_{version.partition('.')[0]}"

if re.search(r"(?:a|\.dev)\d", version):
if _is_internal_version(version):
print(f"Internal alpha/development tag {git_tag}; no release note required.")
return 0
if package != "cuda_pathfinder" and re.search(r"\.post\d", version):
Expand Down Expand Up @@ -156,6 +172,45 @@ def _check_release_target(version: str, package: str, component: str, repo_root:
return []


class _ReleaseIndexLinks(HTMLParser):
def __init__(self) -> None:
super().__init__()
self.paths: set[str] = set()

def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
if tag == "a":
href = dict(attrs).get("href")
if href is not None:
self.paths.add(href.split("#", 1)[0].split("?", 1)[0].removeprefix("./"))


def _check_rendered_target(docs_root: Path, component: str, version: str) -> int:
# Pathfinder post releases put their exact notes under the base docs directory.
version_dir = version.split(".post", 1)[0]
component_root = docs_root if component == "cuda-python" else docs_root / component
version_root = component_root / version_dir
notes_href = f"release/{version}-notes.html"
rendered_notes = version_root / notes_href
if not rendered_notes.is_file():
print(f"ERROR: missing rendered release notes: {rendered_notes}", file=sys.stderr)
return 1
if rendered_notes.stat().st_size == 0:
print(f"ERROR: empty rendered release notes: {rendered_notes}", file=sys.stderr)
return 1

index = version_root / "release.html"
if not index.is_file():
print(f"ERROR: missing rendered release index: {index}", file=sys.stderr)
return 1
links = _ReleaseIndexLinks()
links.feed(index.read_text(encoding="utf-8"))
if notes_href not in links.paths:
print(f"ERROR: missing relative link to {notes_href} in {index}", file=sys.stderr)
return 1
print(f"Found rendered release notes and release index link: {rendered_notes}")
return 0


def write_version_output(version: str) -> None:
output_path = os.environ.get("GITHUB_OUTPUT")
if output_path:
Expand Down Expand Up @@ -190,8 +245,9 @@ def check_release_notes(
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--git-tag", required=True)
parser.add_argument("--component", choices=list(COMPONENTS), help="required unless --tag-ci is used")
parser.add_argument("--component", choices=[*COMPONENTS, "all"], help="required unless --tag-ci is used")
parser.add_argument("--tag-ci", action="store_true", help="check only file existence for a CI tag push")
parser.add_argument("--rendered-docs", type=Path, help="staged docs payload to check after the source")
parser.add_argument(
"--repo-root",
default=Path("."),
Expand All @@ -209,32 +265,45 @@ def main(argv: list[str] | None = None) -> int:
return _check_tag_ci(args.git_tag, args.repo_root)
if args.component is None:
parser.error("--component is required unless --tag-ci is used")
component = args.component
if component == "all" and args.rendered_docs is not None:
component = _component_for_tag_ci(args.git_tag)

try:
bindings_package = json.loads(args.bindings_package) if args.bindings_package else None
if bindings_package is not None and not isinstance(bindings_package, dict):
raise ValueError("resolved CUDA bindings package must be a JSON object")
target = _release_target_from_tag(args.git_tag, args.component, bindings_package)
target = _release_target_from_tag(args.git_tag, component, bindings_package)
except ValueError as error:
print(f"ERROR: invalid CUDA bindings configuration: {error}", file=sys.stderr)
return 2
if target is None:
print(
f"ERROR: tag {args.git_tag!r} does not match the expected format for component {args.component!r}.",
f"ERROR: tag {args.git_tag!r} does not match the expected format for component {component!r}.",
file=sys.stderr,
)
return 2
version, package = target

if is_post_release(version) and args.component != "cuda-pathfinder":
if args.rendered_docs is not None and _is_internal_version(version):
print(f"Internal alpha/development tag {args.git_tag}; no rendered release note required.")
return 0

if is_post_release(version) and component != "cuda-pathfinder":
print(f"Post-release tag ({args.git_tag}), skipping release-notes check.")
write_version_output(version)
return 0

problems = _check_release_target(version, package, args.component, args.repo_root)
problems = _check_release_target(version, package, component, args.repo_root)

if not problems:
print(f"Release notes present for tag {args.git_tag}, component {args.component}.")
if args.rendered_docs is not None:
source = args.repo_root / notes_path(package, version)
if component == "cuda-pathfinder" and source.stat().st_size == 0:
print(f"Empty Pathfinder release note placeholder {source}; no rendered release note required.")
return 0
return _check_rendered_target(args.rendered_docs, component, version)
print(f"Release notes present for tag {args.git_tag}, component {component}.")
write_version_output(version)
return 0

Expand Down
107 changes: 107 additions & 0 deletions ci/tools/tests/test_check_rendered_release_notes.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

from __future__ import annotations

import json

import pytest

from ci.tools.check_tagged_release_notes import main, notes_path


def check_rendered(root, tag, component, bindings_package=None):
args = [
"--git-tag",
tag,
"--component",
component,
"--repo-root",
str(root / "source"),
"--rendered-docs",
str(root / "artifacts" / "docs"),
]
if bindings_package is not None:
args.extend(("--bindings-package", json.dumps(bindings_package)))
return main(args)


def write_source(root, package, version, content="Release notes."):
path = root / "source" / notes_path(package, version)
path.parent.mkdir(parents=True)
path.write_text(content, encoding="utf-8")


def write_html(root, versioned_path, version, href, *, note=True):
versioned_root = root / "artifacts" / "docs" / versioned_path
(versioned_root / "release").mkdir(parents=True, exist_ok=True)
(versioned_root / "release.html").write_text(f'<a href="{href}">Release notes</a>', encoding="utf-8")
if note:
(versioned_root / "release" / f"{version}-notes.html").write_text("<h1>Release notes</h1>", encoding="utf-8")


@pytest.mark.parametrize(
("failure", "expected_error"),
[
("missing-page", "missing rendered release notes"),
("wrong-link", "missing relative link"),
],
)
@pytest.mark.agent_authored(model="gpt-6")
def test_required_bindings_page_and_link_must_be_in_the_versioned_tree(tmp_path, capsys, failure, expected_error):
version = "12.9.11rc1"
component = "cuda-bindings"
versioned_path = f"{component}/{version}"
href = f"release/{version}-notes.html"
package = {"package_root": "cuda_bindings_12", "release_version": version}
write_source(tmp_path, "cuda_bindings_12", version)
write_html(tmp_path, f"{component}/latest", version, href)
broken_href = f"../latest/{href}" if failure == "wrong-link" else href
write_html(tmp_path, versioned_path, version, broken_href, note=failure != "missing-page")

assert check_rendered(tmp_path, f"v{version}", component, package) == 1
assert expected_error in capsys.readouterr().err

write_html(tmp_path, versioned_path, version, href)
assert check_rendered(tmp_path, f"v{version}", component, package) == 0


@pytest.mark.agent_authored(model="gpt-6")
def test_metapackage_payload_is_flat(tmp_path):
version = "13.5.1"
write_source(tmp_path, "cuda_python", version)
write_html(tmp_path, version, version, f"release/{version}-notes.html")

assert check_rendered(tmp_path, f"v{version}", "cuda-python") == 0


@pytest.mark.agent_authored(model="gpt-6")
def test_all_checks_the_component_selected_by_the_tag(tmp_path):
version = "1.3.1"
write_source(tmp_path, "cuda_core", version)
write_html(tmp_path, f"cuda-core/{version}", version, f"release/{version}-notes.html")

assert check_rendered(tmp_path, f"cuda-core-v{version}", "all") == 0


@pytest.mark.parametrize("tag", ("cuda-core-v1.3.1a0", "cuda-core-v1.3.1.dev1", "cuda-core-v1.3.1.post1"))
@pytest.mark.agent_authored(model="gpt-6")
def test_tags_without_required_notes_need_no_rendered_page(tmp_path, tag):
assert check_rendered(tmp_path, tag, "cuda-core") == 0


@pytest.mark.parametrize("content", ("", "Post-release notes."))
@pytest.mark.agent_authored(model="gpt-6")
def test_pathfinder_post_release_requires_rendered_notes_for_nonempty_source(tmp_path, capsys, content):
version = "1.9.1.post1"
tag = f"cuda-pathfinder-v{version}"
write_source(tmp_path, "cuda_pathfinder", version, content)
if not content:
assert check_rendered(tmp_path, tag, "all") == 0
return

assert check_rendered(tmp_path, tag, "all") == 1
assert "missing rendered release notes" in capsys.readouterr().err

write_html(tmp_path, "cuda-pathfinder/1.9.1", version, f"release/{version}-notes.html")
assert check_rendered(tmp_path, tag, "all") == 0
Loading