Skip to content

[doc-only] Fix documentation selector publication timing - #3520

Merged
rwgk merged 4 commits into
mainfrom
rwgk/docs-selector-publication-timing
Nov 21, 2026
Merged

rwgk merged 4 commits into
mainfrom
rwgk/docs-selector-publication-timing

Conversation

@rwgk

@rwgk rwgk commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

— codex GPT-6 on behalf of Ralf —

Description

Adding numeric release notes for an upcoming release forced a public version-selector entry before its documentation existed. Core 1.4.0 consequently appeared in the live dropdown with a destination that returned 404.

Remove the selector requirement and its obsolete tests from the staged release-note hook, keeping bindings/metapackage note pairing intact. Remove the premature Core 1.4.0 selector entry while retaining its release notes. The always-run hook now exercises this real case in both native pre-commit CI jobs.

Correct the Core and bindings release guides, all five package documentation READMEs, and CI documentation: local builds need no selector entry; add release entries on main after the component is published and its versioned documentation is deployed. Main deployments own the shared selectors; a missing entry can be repaired there without changing a release tag.

Inspected cuda_bindings_12/docs/build_docs.sh and cuda_bindings_13/docs/build_docs.sh: CUDA 12 consumes CUDA 13's canonical selector, so no root-specific build changes are needed. No SYNCED blocks are touched.

Validation:

  • 75 existing staged-note, tag-CI, and publication-preflight tests pass on Python 3.11.
  • pre-commit run --all-files passes, including the staged-note hook with Core 1.4.0's selector entry removed.
  • Public CI passed before the README-only review follow-up: CI-tool tests, API checks, all seven Linux builds, documentation and rendered-link checks, and preview deployment.
  • Native Linux and Windows pre-commit CI passed before that follow-up.
  • The README-only review follow-up passes local pre-commit run --all-files, including authored-link checks. Full CUDA CI is intentionally deferred for that follow-up; automatic direct PR checks may run.

The [doc-only] title directive retains CI-tool tests, pre-commit checks, Linux builds, and documentation validation while skipping package runtime tests. These changes affect release-note tooling, selector metadata, and release guidance.

Checklist

  • I have read the Contributing Guidelines.
  • New or existing tests cover these changes.
  • The documentation is up to date with these changes.

rwgk added 2 commits November 20, 2026 14:33
Signed-off-by: Ralf W. Grosse-Kunstleve <rgrossekunst@nvidia.com>
@copy-pr-bot

copy-pr-bot Bot commented Nov 20, 2026

Copy link
Copy Markdown
Contributor

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

@github-actions github-actions Bot added CI/CD CI/CD infrastructure cuda.core Everything related to the cuda.core module labels Nov 20, 2026
@rwgk rwgk added this to the CI milestone Nov 20, 2026
@rwgk rwgk added bug Something isn't working documentation Improvements or additions to documentation and removed cuda.core Everything related to the cuda.core module labels Nov 20, 2026
@rwgk rwgk self-assigned this Nov 20, 2026
@rwgk

rwgk commented Nov 20, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test ae5f0ec

@coderabbitai

coderabbitai Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Summary

Summary by CodeRabbit

  • Documentation
    • Clarified that shared version switchers are updated on main only after versioned documentation is published and deployed. Release deployments do not update shared selectors or latest pages.
    • Release notes may be merged before publication without a switcher entry. Missing entries should be corrected on main without changing the release tag.
    • Updated documentation build guidance: local builds do not require a version-selector entry, and older versioned pages should remain available.
    • Updated release-note check guidance to focus on matching bindings and Python release notes.
  • Chores
    • Removed CUDA Core 1.4.0 from the version list.

Release guidance separates release-note pairing from documentation selector updates. The staged checker validates paired bindings and metapackage release notes. Selector entries are added on main after versioned documentation is published and deployed.

Changes: Release workflow

Layer / File(s) Summary
Publication-gated selector updates
.github/RELEASE-bindings.md, .github/RELEASE-core.md, cuda_core/docs/nv-versions.json, cuda_bindings_12/docs/README.md, cuda_bindings_13/docs/README.md, cuda_core/docs/README.md, cuda_pathfinder/docs/README.md, cuda_python/docs/README.md
Release instructions and package documentation defer selector updates until versioned documentation is published and deployed. They state that main controls shared selectors and that missing entries should be fixed on main without changing the release tag. The CUDA Core version list no longer includes 1.4.0.
Staged release-note pairing
ci/tools/check_staged_release_notes.py, ci/tools/tests/test_check_release_note_selectors.py, .pre-commit-config.yaml, ci/README.md
The staged checker now checks only paired bindings and metapackage release notes. Its hook label and documentation no longer describe selector validation. The selector-validation test module was removed.

Possibly related PRs

  • NVIDIA/cuda-python#3498: Adds selector checks to the staged hook, which this change removes, and changes selector ownership.

Suggested reviewers: leofang

Change: Other

Merge Risk: Minimal · up to 34dba

This change moves documentation selector updates to after publication and removes the premature Core 1.4.0 entry. Release-note pairing checks remain in place, and no runtime behavior changes. It is ready to merge.

Architecture risk: Low · up to 34dba

The change affects 6 systems.

Changed systems: ci, cuda_core, cuda_bindings_12, cuda_bindings_13, cuda_pathfinder, cuda_python

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

  • observed — ci (service) was modified; 3 changed files map to changed impact.
  • observed — cuda_core (service) was modified; 2 changed files map to changed impact.
  • observed — cuda_bindings_12 (service) was modified; 1 changed file maps to changed impact.
  • observed — cuda_bindings_13 (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

  • observed — Modified behavior in ci/tools/check_staged_release_notes.py: The module description now covers staged bindings and metapackage release-note pairs. The release-note pattern no longer matches cuda_core or cuda_pathfinder paths, and the json import and selector URL configuration were removed.
  • observed — Modified behavior in ci/tools/check_staged_release_notes.py: The Git index listing no longer includes cuda_core or cuda_pathfinder release-note paths.
  • observed — Modified behavior in ci/tools/check_staged_release_notes.py: Release notes that match the narrowed path pattern are now included according to _requires_pairing; the former package-specific thresholds for cuda_core and cuda_pathfinder were removed.
  • observed — Modified behavior in ci/tools/check_staged_release_notes.py: main now checks and reports only missing release-note pairs. It no longer combines selector errors with pairing errors, and its failure guidance now names matching cuda-bindings and cuda-python release notes.
- [ ] Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 9302bf8 and 34dbaaa.

Files selected for processing: 5

  • cuda_bindings_12/docs/README.md
  • cuda_bindings_13/docs/README.md
  • cuda_core/docs/README.md
  • cuda_pathfinder/docs/README.md
  • cuda_python/docs/README.md

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

Nitpick comments: 1

ci/tools/tests/test_check_staged_release_notes.py: 1

41-51: Trivial · Maintainability & Code Quality · Quick win

suggestion: Remove the test for an explicit hook failure.

This test checks that the hook accepts release notes without selectors. An incorrect rejection already produces an immediate CI failure through the always-run hook. It does not produce a silent wrong outcome.

As per coding guidelines, “Keep a test only when wrong behavior would be silent.”

Source: Coding guidelines

Review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between de0af8d and ae5f0ec.

Files selected for processing: 8

  • .github/RELEASE-bindings.md
  • .github/RELEASE-core.md
  • .pre-commit-config.yaml
  • ci/README.md
  • ci/tools/check_staged_release_notes.py
  • ci/tools/tests/test_check_release_note_selectors.py
  • ci/tools/tests/test_check_staged_release_notes.py
  • cuda_core/docs/nv-versions.json
Files with no reviewable changes: 2

  • ci/tools/tests/test_check_release_note_selectors.py
  • cuda_core/docs/nv-versions.json

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.

Comment thread ci/README.md Resolved
Signed-off-by: Ralf W. Grosse-Kunstleve <rgrossekunst@nvidia.com>
@github-actions github-actions Bot added the cuda.core Everything related to the cuda.core module label Nov 20, 2026
@rwgk

rwgk commented Nov 20, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test 9302bf8

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor
Doc Preview CI
Preview removed because the pull request was closed or merged.

@rwgk
rwgk requested review from Andy-Jost and juenglin November 21, 2026 00:16
@juenglin

Copy link
Copy Markdown
Contributor

Nit: step 2 of the package docs READMEs still says "Ensure the version is included in nv-versions.json", which reads as if the entry should be added before building/publishing:

  • cuda_core/docs/README.md (line 4)
  • cuda_pathfinder/docs/README.md (line 4)
  • cuda_bindings_13/docs/README.md (line 4)
  • cuda_bindings_12/docs/README.md (lines 9-10)

These are local build instructions, so they don't strictly contradict the new guidance, but it might be worth rewording step 2 (or pointing to the release guide) so nobody preparing a release adds the selector entry too early again.

Signed-off-by: Ralf W. Grosse-Kunstleve <rgrossekunst@nvidia.com>
@github-actions github-actions Bot added cuda.bindings Everything related to the cuda.bindings module cuda.pathfinder Everything related to the cuda.pathfinder module labels Nov 21, 2026
@rwgk

rwgk commented Nov 21, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test 34dbaaa

@rwgk

rwgk commented Nov 21, 2026

Copy link
Copy Markdown
Contributor Author

it might be worth rewording step 2 (or pointing to the release guide) so nobody preparing a release adds the selector entry too early again.

Done: 34dbaaa

Thanks for catching this!

@rwgk
rwgk enabled auto-merge (squash) November 21, 2026 02:06
@rwgk
rwgk merged commit b12c265 into main Nov 21, 2026
43 checks passed
@rwgk
rwgk deleted the rwgk/docs-selector-publication-timing branch November 21, 2026 02:20
github-actions Bot pushed a commit that referenced this pull request Nov 21, 2026
Removed preview folders for the following PRs:
- PR #2924
- PR #3470
- PR #3490
- PR #3511
- PR #3515
- PR #3516
- PR #3520
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working CI/CD CI/CD infrastructure cuda.bindings Everything related to the cuda.bindings module cuda.core Everything related to the cuda.core module cuda.pathfinder Everything related to the cuda.pathfinder module documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants