From 01b90227bf2baff6ea69b13219c4c7eb01b06f26 Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Fri, 20 Nov 2026 21:31:44 -0800 Subject: [PATCH 1/3] Validate rendered release notes before uploading docs --- .github/workflows/build-docs.yml | 13 +++ ci/tools/check_tagged_release_notes.py | 95 +++++++++++++--- .../test_check_rendered_release_notes.py | 107 ++++++++++++++++++ 3 files changed, 202 insertions(+), 13 deletions(-) create mode 100644 ci/tools/tests/test_check_rendered_release_notes.py diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index b27f956e8f1a..98b950da975f 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -363,6 +363,19 @@ jobs: fi mv "${COMPONENT}"/docs/build/html/* "artifacts/docs/${TARGET}" + - 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" + # Check links and anchors in the rendered HTML built above. # Links in authored Markdown and reST files are checked separately by the # ordinary Linux/Windows pre-commit jobs. diff --git a/ci/tools/check_tagged_release_notes.py b/ci/tools/check_tagged_release_notes.py index d666cb24d51d..627c043943bc 100644 --- a/ci/tools/check_tagged_release_notes.py +++ b/ci/tools/check_tagged_release_notes.py @@ -6,6 +6,7 @@ Usage: python -m ci.tools.check_tagged_release_notes --git-tag --component python -m ci.tools.check_tagged_release_notes --tag-ci --git-tag + python -m ci.tools.check_tagged_release_notes --git-tag --component --rendered-docs 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 @@ -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: @@ -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 @@ -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): @@ -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: @@ -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("."), @@ -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 diff --git a/ci/tools/tests/test_check_rendered_release_notes.py b/ci/tools/tests/test_check_rendered_release_notes.py new file mode 100644 index 000000000000..b4864b1b83ac --- /dev/null +++ b/ci/tools/tests/test_check_rendered_release_notes.py @@ -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'Release notes', encoding="utf-8") + if note: + (versioned_root / "release" / f"{version}-notes.html").write_text("

Release notes

", 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 From 117edc96a28e37c7bc4150cf6c950f337ee39f0b Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Fri, 20 Nov 2026 21:31:49 -0800 Subject: [PATCH 2/3] ci: require manual copy-pr-bot approval From f50b054241acb5d5f52162828014e69a47730503 Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Fri, 20 Nov 2026 21:45:50 -0800 Subject: [PATCH 3/3] Keep rendered notes validation next to docs upload --- .github/workflows/build-docs.yml | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index 98b950da975f..a2df74f0034a 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -363,19 +363,6 @@ jobs: fi mv "${COMPONENT}"/docs/build/html/* "artifacts/docs/${TARGET}" - - 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" - # Check links and anchors in the rendered HTML built above. # Links in authored Markdown and reST files are checked separately by the # ordinary Linux/Windows pre-commit jobs. @@ -396,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