[no-ci] Fix backport release checks and add release dry-run

[rwgk]

Description

Closes #2141.

Supersedes #2143. PR #2143 was useful for unblocking the 12.9.7 release process quickly, but this PR replaces it with a narrower and more maintainable fix for the release workflow.

This PR fixes the issue that blocked the 12.9.7 release process and, just as importantly, makes the release workflow easy to test before an actual release. The new dry-run mode validates the release path without publishing to GitHub Releases, TestPyPI, or PyPI, and it can optionally deploy generated docs to a non-production gh-pages-* branch so we can inspect the docs exactly as they would be published before running the real release.

Fix

The release-note check now runs from the workflow branch, not from the release tag checkout. This keeps the checker on current CI tooling while still using the requested tag as the release identity/source for the release build.

For cuda-bindings and cuda-python mainline releases, the workflow now also requires an explicit backport decision:

• provide the planned backport tag, such as v12.9.7; or
• set backport-git-tag to not planned.

For cuda-bindings and cuda-python, the tag inputs are interpreted differently for mainline and backport releases. For a mainline release, the mainline release notes are required, and backport-git-tag must either name the planned backport tag or be set to not planned. If a planned backport tag is provided, the corresponding backport release notes are required too, and missing or empty notes fail the mainline release. For an actual backport release, backport-git-tag is left blank; the checker looks for release notes for the backport tag itself, but missing or empty notes only emit a GitHub Actions warning so they do not block an otherwise valid package release late in the process. With the mainline-time backport-git-tag check in place, that warning case is not expected to occur in normal release flow.

The docs workflow also accepts older release-tag source trees that still have ci/versions.json instead of ci/versions.yml.

Dry-Run Mode

The manual release workflow now has a release-action input:

• dry-run is the default and safe choice.
• full-release must be selected deliberately for the real release.

In dry-run mode:

• the release tag is still validated;
• release notes are checked;
• the artifact run ID is resolved or accepted from the user;
• source archives are created and checksummed;
• wheels are downloaded and validated against the release tag;
• docs are generated from the release tag;
• GitHub release draft checks/creation are skipped;
• GitHub release asset uploads are skipped;
• TestPyPI and PyPI publishing are skipped;
• dry-run release artifacts are uploaded as workflow artifacts.

If dry-run-docs-branch is provided, the workflow deploys generated docs to that branch. The branch must match gh-pages-*, for example gh-pages-dry-run, and this input is rejected for full-release.

Dry-Run Docs Branch Reset

Before a release dry-run batch, reset the dry-run docs branch to the current production docs branch:

git fetch upstream
git push --force-with-lease=refs/heads/gh-pages-dry-run upstream \
  refs/remotes/upstream/gh-pages:refs/heads/gh-pages-dry-run

Then run the dry-run workflows sequentially, using dry-run-docs-branch: gh-pages-dry-run. After the batch finishes, fetch upstream/gh-pages-dry-run and compare it with upstream/gh-pages to inspect the exact generated docs update before running full-release.

Validation

Focused unit coverage was added for the release-note checker, including:

• loading the configured backport branch;
• requiring a backport decision for mainline cuda-bindings and cuda-python
  releases;
• accepting not planned;
• validating planned backport release notes;
• warning rather than failing for missing notes on actual backport releases;
• rejecting malformed or non-backport planned tags.

I also tested the PR exhaustively with a four-run dry-run batch:

1. cuda-bindings, v13.3.1
2. cuda-python, v13.3.1
3. cuda-bindings, v12.9.7
4. cuda-python, v12.9.7

Full test report:

#2161 (comment)

The batch verified both the mainline and backport release paths for both components, including release-note checks, artifact validation, skipped external publishing, and docs deployment to gh-pages-dry-run.

[copy-pr-bot]

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.

[rwgk]

Comprehensive dry-run testing report

I tested this PR with a four-run dry-run batch designed to approximate the
release sequence we would use for both mainline and backport releases:

1. cuda-bindings, v13.3.1
2. cuda-python, v13.3.1
3. cuda-bindings, v12.9.7
4. cuda-python, v12.9.7

All four workflow runs completed successfully. The batch exercised:

• mainline release-note handling with backport-git-tag: not planned;
• backport release-note handling with blank backport-git-tag;
• dry-run release artifact validation without publishing to GitHub Releases,
  TestPyPI, or PyPI;
• docs generation from the release tag;
• dry-run docs deployment to gh-pages-dry-run;
• sequential docs updates where the second backport component run preserved the
  docs written by the first backport component run.

Workflow runs

#	Component	Git tag	Workflow run	Result
1	cuda-bindings	v13.3.1	https://github.com/NVIDIA/cuda-python/actions/runs/26918388859	success
2	cuda-python	v13.3.1	https://github.com/NVIDIA/cuda-python/actions/runs/26919456751	success
3	cuda-bindings	v12.9.7	https://github.com/NVIDIA/cuda-python/actions/runs/26919970969	success after rerun
4	cuda-python	v12.9.7	https://github.com/NVIDIA/cuda-python/actions/runs/26921351868	success

Run 3 needed a rerun because of an infrastructure failure. The rerun succeeded,
and GitHub reports the latest attempt as successful.

Common checks verified

For all four runs:

• The workflow ran from check-release-notes_with_backport-git-tag at
  86cc688be2228ca35d2a52cec7df10f8665827c7.
• release-action was dry-run.
• dry-run-docs-branch was gh-pages-dry-run.
• Release notes validation passed.
• Docs generation succeeded.
• Release archive creation and wheel validation ran.
• GitHub release asset upload was skipped.
• TestPyPI publishing was skipped.
• PyPI publishing was skipped.
• Dry-run release artifacts were uploaded as workflow artifacts.

Per-run observations

1. cuda-bindings v13.3.1

Workflow: https://github.com/NVIDIA/cuda-python/actions/runs/26918388859

Observed inputs:

• component: cuda-bindings
• git-tag: v13.3.1
• release-action: dry-run
• backport-git-tag: not planned
• dry-run-docs-branch: gh-pages-dry-run
• run-id: 26663354706

Result:

• Release notes validation passed.
• Docs built from v13.3.1.
• No files changed on gh-pages-dry-run.
• upstream/gh-pages and upstream/gh-pages-dry-run both remained at
  0824a79330b9d45fb775bb4b0372dbc54388a61c.

2. cuda-python v13.3.1

Workflow: https://github.com/NVIDIA/cuda-python/actions/runs/26919456751

Observed inputs:

• component: cuda-python
• git-tag: v13.3.1
• release-action: dry-run
• backport-git-tag: not planned
• dry-run-docs-branch: gh-pages-dry-run
• run-id: 26663354706

Result:

• Release notes validation passed.
• Docs built from v13.3.1.
• The deploy action targeted gh-pages-dry-run and reported:
  There is nothing to commit. Exiting early.
• No files changed on gh-pages-dry-run.
• upstream/gh-pages and upstream/gh-pages-dry-run still matched at
  0824a79330b9d45fb775bb4b0372dbc54388a61c.

3. cuda-bindings v12.9.7

Workflow: https://github.com/NVIDIA/cuda-python/actions/runs/26919970969

Observed inputs from the successful rerun:

• component: cuda-bindings
• git-tag: v12.9.7
• release-action: dry-run
• backport-git-tag: blank
• dry-run-docs-branch: gh-pages-dry-run
• run-id: 26491171597

Result:

• Release notes validation passed as a backport release.
• Docs built from v12.9.7.
• gh-pages-dry-run advanced from
  0824a79330b9d45fb775bb4b0372dbc54388a61c to
  ad1ebe50a57dad930e5afd7fb2f0b932f9427ce4.
• The docs deploy commit was Deploy release docs: v12.9.7.
• 104 docs files changed, all under docs/cuda-bindings/12.9.7/, plus
  docs/cuda-bindings/objects.inv and docs/cuda-bindings/versions.json.

4. cuda-python v12.9.7

Workflow: https://github.com/NVIDIA/cuda-python/actions/runs/26921351868

Observed inputs:

• component: cuda-python
• git-tag: v12.9.7
• release-action: dry-run
• backport-git-tag: blank
• dry-run-docs-branch: gh-pages-dry-run
• run-id: 26491171597

Result:

• check-tag verified v12.9.7 and skipped GitHub release draft work because
  this was a dry run.
• Release notes validation passed as a backport release.
• Docs built from v12.9.7.
• gh-pages-dry-run advanced from
  ad1ebe50a57dad930e5afd7fb2f0b932f9427ce4 to
  f4581dbc59645e843cf18ff6dbb1634839fcd3ae.
• The docs deploy commit was Deploy release docs: v12.9.7.
• 15 docs files changed: top-level docs/12.9.7/..., plus
  docs/objects.inv and docs/versions.json.
• This run did not overwrite the docs/cuda-bindings/12.9.7/... files written
  by run 3.

Final docs branch state

After the four-run batch:

• gh-pages-dry-run ended at
  f4581dbc59645e843cf18ff6dbb1634839fcd3ae.
• The two v13.3.1 dry-runs produced no docs branch changes because the
  generated output matched the seeded branch.
• The two v12.9.7 dry-runs produced the expected backport docs updates.
• The final diff from upstream/gh-pages to upstream/gh-pages-dry-run
  contained 119 docs files total:
  • 104 from cuda-bindings v12.9.7;
  • 15 from cuda-python v12.9.7.

This confirms that the dry-run mode exercised the release validation path and
docs deployment path with high fidelity, while avoiding external publishing
side effects.

Conclusion

The four-run batch passed and covered the intended mainline/backport and
component matrix:

• cuda-bindings mainline dry-run
• cuda-python mainline dry-run
• cuda-bindings backport dry-run
• cuda-python backport dry-run

The checks validate the PR's two intended behaviors:

• the release-note checker handles mainline and backport releases correctly;
• the dry-run release workflow validates artifacts and docs deployment without
  publishing to GitHub Releases, TestPyPI, or PyPI.

---

Screenshots from triggering the workflow runs

---

---

---