[doc-only] Fix release notes checks for backport releases#2143
Conversation
|
Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually. Contributors can view more details about this message here. |
First 12.9.7 Release Attempt Failure AnalysisWorkflow run: Good news: the new release-notes check passed. The failure is later, in the reusable docs workflow: Run inputs:
Root cause:
However, the with: {
"cuda": {
"build": {
"version": "12.9.1"
}
}
}So this is the same general compatibility class as issue #2141: a current workflow is being run against an older backport tag whose source tree predates some workflow/tooling assumptions. Recommended fix: Update
This should let the |
12.9.7 Release Run Log AnalysisWorkflow run: Summary: the run succeeded, and the core release path looks healthy. What succeeded:
Benign warnings/noise observed:
Remaining issue: The versioned 12.9.7 docs are live, but they do not contain the 12.9.7 release notes page: currently returns 404. The same release-note page does exist in the 13.3.0 docs: Root cause:
So PR 2143 now fixes:
But it does not yet make backport versioned docs include release-note files that exist only on Recommendation: Add one more narrow fix to PR 2143: before building release docs, overlay the component's Important constraints:
That should make a rerun of the while preserving the intended source-of-truth model for backport release notes. |
Plan: Add a Docs-Only Release Workflow ModeMotivationThe 12.9.7 release run succeeded for publishing, but exposed a docs-only follow-up need: the generated Rerunning the whole release workflow is unnecessarily risky after wheels have already been published to PyPI and uploaded to the GitHub release. We need a safe way to repair or regenerate release docs without touching package publication or release assets. Proposed UIAdd a new release-action:
description: "What to run"
required: true
type: choice
options:
- full-release
- docs-only
default: full-releaseThe default should preserve current behavior. Behavior
RationaleUse The docs job should still keep
Implementation Plan
if: ${{ inputs.release-action == 'full-release' }}
ValidationSince this is workflow control-flow only:
|
Analysis: 12.9.7 docs-only release runWorkflow run: SummaryThe docs-only release run succeeded and fixed the missing https://nvidia.github.io/cuda-python/cuda-bindings/12.9.7/release/12.9.7-notes.html The run used the new
This confirms that the docs-only mode repaired release documentation without touching PyPI or GitHub release assets. Relevant log detailsThe release notes checker found the expected backport notes: The docs workflow ran the new overlay steps:
The docs build completed successfully and deployed the regenerated release docs: Warning analysisThe most notable warning class was: This is caused by the broad release-note overlay. Some older release tags still contain historical notes as These warnings are non-fatal and did not prevent the docs build or deployment. The target page for the repair, DecisionWe should keep the broad overlay behavior for PR 2143. Although it can produce harmless duplicate-source warnings when an older tag has For this manual repair workflow, that benefit is more important than avoiding non-fatal Sphinx warning noise. No further fix is recommended for PR 2143 based on this run. |
Analysis: cuda-python 12.9.7 release runWorkflow run: SummaryThe The run completed all expected full-release jobs successfully:
The workflow auto-detected the successful tag-triggered artifact run: The release-note check passed for the backport release: Package publicationThe package publication path looks good. The workflow downloaded and validated the expected metapackage wheel: Both TestPyPI and PyPI uploads succeeded: PyPI now has GitHub release assetsThe upload job succeeded and uploaded the source archive, checksum, and The GitHub release is still a draft, which matches the current workflow behavior: The assets include:
Docs resultThe docs build and deployment job succeeded: The https://nvidia.github.io/cuda-python/12.9.7/release/12.9.7-notes.html The page includes:
Docs warning and remaining issueOne docs issue remains. The The relevant warnings are: Root cause: the old This differs from the earlier RecommendationTreat the package release itself as successful. No PyPI or GitHub asset follow-up is needed for Before calling PR 2143 complete, add one more docs-overlay fix:
That should keep the already-successful package release untouched while regenerating the |
Release docs builds start from the requested release tag, then overlay release-note sources from the workflow branch. Older tags can contain docs/source/release.md, while the workflow branch now provides docs/source/release.rst. Both files map to the same Sphinx document name, release. If both remain in the tag checkout, Sphinx can keep using the stale Markdown index and leave newly overlaid release-note pages orphaned. Remove the old release.md whenever release.rst is overlaid so the newer index controls the versioned docs build. This only resolves the top-level release index conflict. The broad *-notes.rst overlay remains intentional so fixes to historical release notes on the workflow branch can be propagated to older published docs.
Analysis: cuda-python 12.9.7 docs-only run and version selectorWorkflow run: Workflow log analysisThe docs-only run succeeded and used the intended safety path. The completed jobs were:
The workflow ran from branch The run auto-detected the existing successful tag-triggered artifact run: The release-note check passed: The overlay step used the latest PR 2143 fix: The previous top-level source conflict is fixed. The prior run emitted: This run no longer emits that warning. The docs build succeeded: The remaining warnings are expected from the intentionally broad historical release-note overlay: These warnings are non-fatal and consistent with the intended behavior: newer The generated https://nvidia.github.io/cuda-python/12.9.7/release.html It includes Version selector analysisThe incomplete bottom-left The older <script src="{{ pathto('_static/javascripts/version_dropdown.js', 1) }}"></script>
<script>
var jsonLoc = "{{ pathto('../versions.json', 1) }}";
var targetLoc = "{{ pathto('../', 1) }}";
add_version_dropdown(jsonLoc, targetLoc, currentVersion);
</script>That legacy dropdown reads: That file currently contains only: This exactly matches the incomplete version selector shown in both screenshots. The newer complete version metadata exists separately: It includes: Newer docs use RecommendationKeep For compatibility with older published docs, {
"latest": "latest",
"13.3.0": "13.3.0",
"13.2.0": "13.2.0",
...
"12.6.1": "12.6.1"
}Then rerun the release workflow in
After commit ac092a0:
|
Keep nv-versions.json as the release docs source of truth, but derive the legacy versions.json consumed by older Furo-based cuda-python docs during release overlays. This lets docs-only repair runs update the old bottom-left version selector without touching package publication or GitHub release assets.
Analysis: cuda-python 12.9.7 docs-only run after version-selector fixWorkflow run: SummaryThe docs-only repair run succeeded and behaved as intended. The run used branch That is the commit adding the legacy Job behaviorThe workflow followed the expected docs-only path:
This confirms the run did not touch PyPI, TestPyPI, source archives, or GitHub release assets. The workflow auto-detected the same successful tag-triggered artifact run as before: The release-note check passed: Docs buildThe docs build and deployment succeeded: The overlay step ran and the log shows the expected generated/overlaid metadata files, including The previous top-level The remaining warnings are expected and non-fatal:
Version selectorThe deployed legacy selector metadata is now complete.
The but that file now has the complete version list, so the bottom-left legacy selector is complete as shown in the screenshot. ConclusionThe release-notes index and the legacy version selector are now both repaired for No further workflow or docs repair is recommended based on this run.
|
|
/ok to test |
|



Description
Fixes #2141.
This PR makes the manual release workflow safe and usable for backport tags such as
v12.9.7, where the tag source tree can predate current release tooling and docs metadata. It also adds a docs-only repair path so already-published releases can have versioned docs regenerated without touching PyPI or GitHub release assets.Background
The release workflow originally checked out the requested release tag before running release-note checks. That broke for older backport tags because
v12.9.7did not contain the currentci/tools/check_release_notes.pytooling.After fixing that, the
v12.9.7release exposed two more older-tag compatibility issues:build-docs.ymlexpectedci/versions.yml, butv12.9.7still hadci/versions.json.main, so building docs directly from the old tag omitted newer*-notes.rstfiles.This PR handles those compatibility gaps while preserving the intended model: versioned docs are still built from the release tag, with only release-note and version-selector metadata overlaid from the workflow branch.
Changes
Add
backport-git-taghandling to the release-note checker.cuda-bindings/cuda-pythonreleases must explicitly state a planned backport tag ornot planned.Run release-note checks from the workflow branch instead of from the release tag checkout.
Support older docs version metadata.
build-docs.ymlnow readsci/versions.ymlwhen present and falls back toci/versions.jsonfor older tags.Overlay release-note sources before release docs builds.
docs/source/release/*-notes.rstinto the checked-out release tag tree.docs/source/release.rst; if an older tag has stalerelease.md, that file is removed so Sphinx uses the overlaidrelease.rstindex.Add a
docs-onlyrelease workflow mode.full-releaseremains the default and preserves current package publication behavior.docs-onlyruns release-note checks, resolves the artifact run ID, builds docs, and deploys docs.docs-onlyskips GitHub release draft checking/creation, source archive upload, GitHub release wheel upload, TestPyPI, and PyPI.Keep old Furo-based
cuda-pythonversion selectors complete.nv-versions.jsonremains the source of truth.versions.jsonconsumed by oldercuda-pythondocs fromnv-versions.json.cuda_python/docs/versions.jsonis refreshed to match the complete version list.Validation
Focused tests:
ci/tools/tests/test_check_release_notes.pyManual release workflow validation:
First
v12.9.7attempt failed in docs because the tag hadci/versions.json, notci/versions.yml.After adding the legacy metadata fallback, the
cuda-bindings v12.9.7full release succeeded.After adding release-note overlays and
docs-only, thecuda-bindings 12.9.7docs-only repair succeeded and published the missing release-note page without touching PyPI or GitHub release assets.The
cuda-python v12.9.7full release succeeded and published the metapackage.After fixing the
release.md/release.rstindex conflict, thecuda-python 12.9.7docs-only repair succeeded and made the full overlaid release-note list visible.After deriving legacy
versions.jsonfromnv-versions.json, the finalcuda-python 12.9.7docs-only repair succeeded and restored the complete old Furo version selector.Notes
The broad release-note overlay can produce harmless Sphinx warnings when an older tag contains historical
*-notes.mdfiles and the workflow branch overlays corresponding*-notes.rstfiles. This is intentional: it allows docs-only repair runs to propagate fixes to historical release notes maintained on the workflow branch into already-published versioned docs.The top-level release index conflict is handled separately by removing stale
release.mdwhen an overlaidrelease.rstis present, because those two files map to the same Sphinx document name.