From 98cc331d763a8a47fcf64c09e8d6e8fce838c0ef Mon Sep 17 00:00:00 2001 From: Andy Jost Date: Mon, 23 Feb 2026 12:32:54 -0800 Subject: [PATCH 1/2] [docs-only] Add release process guide and update release checklist Add .github/RELEASE.md with step-by-step guidance for each item in the release checklist, based on lessons learned from the cuda.core v0.6.0 release. Remove obsolete checklist items (RC tag, pre-release QA, nvidia conda channel upload). Co-authored-by: Cursor --- .github/ISSUE_TEMPLATE/release_checklist.yml | 10 +- .github/RELEASE.md | 267 +++++++++++++++++++ 2 files changed, 270 insertions(+), 7 deletions(-) create mode 100644 .github/RELEASE.md diff --git a/.github/ISSUE_TEMPLATE/release_checklist.yml b/.github/ISSUE_TEMPLATE/release_checklist.yml index 1c8dbc36ff..cca1c0d077 100644 --- a/.github/ISSUE_TEMPLATE/release_checklist.yml +++ b/.github/ISSUE_TEMPLATE/release_checklist.yml @@ -1,4 +1,4 @@ -# SPDX-FileCopyrightText: Copyright (c) 2024-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-FileCopyrightText: Copyright (c) 2024-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # # SPDX-License-Identifier: Apache-2.0 @@ -10,7 +10,7 @@ body: - type: markdown attributes: value: | - This checklist is for cuda-core releases as well as cuda-bindings patches. Please go through this checklist and ensure all tasks are completed. + This checklist is for cuda-core releases as well as cuda-bindings patches. Please go through this checklist and ensure all tasks are completed. See [RELEASE.md](../RELEASE.md) for detailed guidance on each step. - type: checkboxes id: subpackage-tasks @@ -20,17 +20,13 @@ body: - label: File an internal nvbug to communicate test plan & release schedule with QA - label: Ensure all pending PRs are reviewed, tested, and merged - label: Check (or update if needed) the dependency requirements - - label: Create a public rc tag - - label: "Point QA to fetch public artifacts (wheels) from the GHA run ID, example: `gh run download 12323257563 -p \"cuda-core*\" -R NVIDIA/cuda-python`" - - label: Wait for QA reports and fix any issues found - label: "Finalize the doc update, including release notes (\"Note: Touching docstrings/type annotations in code is OK during code freeze, apply your best judgement!\")" - label: Update the docs for the new version - label: Create a public release tag - label: Wait for the tag-triggered CI run to complete, and use that run ID for release workflows - label: If any code change happens, rebuild the wheels from the new tag - - label: Update the conda recipe & release conda packages - - label: Upload conda packages to nvidia channel - label: Upload wheels to PyPI + - label: Update the conda recipe & release conda packages - label: Post-release QA - label: Finalize the announcement update - label: Send out the announcement internally diff --git a/.github/RELEASE.md b/.github/RELEASE.md new file mode 100644 index 0000000000..165a83edb8 --- /dev/null +++ b/.github/RELEASE.md @@ -0,0 +1,267 @@ + + + +# Release Process + +This document provides detailed guidance for each step of the +[Release Checklist](ISSUE_TEMPLATE/release_checklist.yml). To start a +release, create a new issue from that template and work through it item by +item, referring back here as needed. + +--- + +## File an internal nvbug + +Create an nvbug from the SWQA template to request pre-release validation. +To find the template, search for a previous release's nvbug (e.g. by +title "Release of cuda.core") and create a new bug from the same template. + +Example (from the cuda.core v0.6.0 release, +[nvbug 5910741](https://nvbugspro.nvidia.com/bug/5910741)): + +> **Title:** Release of cuda.core v0.6.0 +> +> **Description:** +> +> Requesting SWQA validation for the cuda.core v0.6.0 release. Please test +> the following SW combinations on all listed platforms and report any +> issues found. +> +> **SW Combinations** +> - cuda.core 0.6.0 / cuda.bindings 12.9 / CTK 12.9 / CUDA 12.9 driver +> - cuda.core 0.6.0 / cuda.bindings 13.0 / CTK 13.0 / CUDA 13.0 driver +> - cuda.core 0.6.0 / cuda.bindings 13.1 / CTK 13.1 / CUDA 13.1 driver +> +> **Platforms** +> - Linux x86-64 +> - Linux arm64 +> - Windows x86-64 (TCC and WDDM) +> - WSL +> +> **Test Plan** +> +> Functional tests as described in the cuda.core test plan. +> +> **Release Milestones** +> - Pre-release QA (this request) +> - GitHub release tag and posting +> - PyPI wheel upload +> - Post-release validation + +**How to determine the SW combinations:** + +- **cuda.core version**: The version being released. +- **cuda.bindings, CTK, and CUDA driver versions**: Check with the release owner. + +Update the version, SW combinations, and platforms as appropriate for each +release. + +--- + +## Check (or update if needed) the dependency requirements + +Review `cuda_core/pyproject.toml` and verify the following are current: + +- `requires-python` — supported Python version range +- `dependencies` — runtime dependencies (e.g. `numpy`) +- `[project.optional-dependencies]` — `cuda-bindings` version pins for + `cu12` / `cu13` extras +- `[build-system] requires` — Cython and setuptools version pins +- `[dependency-groups]` — test dependencies (`ml-dtypes`, `cupy`, + `cuda-toolkit` version pins) +- Python version classifiers in `[project]` + +--- + +## Finalize the doc update, including release notes + +Review every PR included in the release. For each one, check whether new +functions, classes, or features were added and whether they have complete +docstrings. Add or edit docstrings as needed — touching docstrings and +type annotations in code is OK during code freeze. + +Write the release notes in `cuda_core/docs/source/release/`. Look at +historical release notes for guidance on format and structure. Balance all +entries for length, specificity, tone, and consistency. Highlight a few +notable items in the highlights section, keeping their full entries in the +appropriate sections below. + +--- + +## Update the docs for the new version + +Add the new version to +`cuda_core/docs/nv-versions.json`. This file drives the version +switcher on the documentation site. Add an entry for the new version +after `"latest"`, following the existing pattern. The docs themselves are +built and deployed automatically by the release workflow. + +--- + +## Create a public release tag + +**Warning:** Pushing a tag is a potentially irrevocable action. Be absolutely +certain the tag points to the correct commit before pushing. + +Tags should be GPG-signed. The tag name format is `cuda-core-v` +(e.g. `cuda-core-v0.6.0`). The tag must point to a commit on `main`. + +```bash +git checkout main +git pull origin main +git tag -s cuda-core-v0.6.0 -m "cuda-core v0.6.0" +git push origin cuda-core-v0.6.0 +``` + +--- + +## Wait for the tag-triggered CI run to complete + +Pushing the tag triggers a CI run automatically. Monitor it in the +**Actions** tab on GitHub. + +- **The docs build is expected to fail** on tag-triggered runs. This is + normal — docs are built during the release workflow instead. +- **All CI tests should succeed.** If any fail, investigate and rerun as + needed. +- Note the **run ID** of the successful tag-triggered run. The release + workflow can auto-detect it from the tag, but you can also provide it + explicitly. + +--- + +## Upload wheels to PyPI + +This is a two-stage process: first publish to TestPyPI, verify, then +publish to PyPI. + +### Stage 1: TestPyPI + +1. Go to **Actions > CI: Release** and run the workflow with: + - **Component**: `cuda-core` + - **The release git tag**: `cuda-core-v0.6.0` + - **The GHA run ID that generated validated artifacts**: This is the + run ID of the successful tag-triggered CI run from the previous step. + You can find it in the URL when viewing the run in the Actions tab + (e.g. `https://github.com/NVIDIA/cuda-python/actions/runs/123456789` + — the run ID is `123456789`). + - **build-ctk-ver**: the `cuda.build.version` from + [`ci/versions.yml`](../ci/versions.yml) (e.g. `13.1.1`) + - **Which wheel index to publish to**: `testpypi` + +2. Wait for the workflow to complete. The docs build step will fail on + forks — this is expected and does not block the wheel upload. + +3. Verify the TestPyPI upload by installing and running tests locally: + + ```bash + pip install -i https://test.pypi.org/simple/ \ + --extra-index-url https://pypi.org/simple/ \ + cuda-core==0.6.0 + cd cuda_core/tests && pytest + ``` + +### Stage 2: PyPI + +Once TestPyPI verification passes, rerun the same workflow with: +- **Which wheel index to publish to**: `pypi` + +After completion, verify: + +```bash +pip install cuda-core==0.6.0 +``` + +--- + +## Update the conda recipe & release conda packages + +The conda-forge feedstock builds from the GitHub Release source archive +(not from PyPI). The bot (`regro-cf-autotick-bot`) does not always pick up +new releases automatically, so you may need to open the PR manually. + +### Fork and clone the feedstock + +```bash +gh repo fork conda-forge/cuda-core-feedstock --clone +cd cuda-core-feedstock +``` + +Optional: Set up remotes so your fork is named after your GitHub username: + +```bash +git remote rename origin +git remote add origin https://github.com/conda-forge/cuda-core-feedstock.git +git fetch origin +``` + +### Update `recipe/meta.yaml` + +Create a branch and edit `recipe/meta.yaml`: + +```bash +git checkout -b update-v0.6.0 origin/main +``` + +Update the following fields: + +1. **`version`**: Set to the new version (e.g. `0.6.0`). +2. **`number`** (build number): Reset to `0` for a new version. +3. **`sha256`**: The SHA-256 of the source archive from the GitHub + Release. Download it and compute the hash: + + ```bash + curl -sL https://github.com/NVIDIA/cuda-python/releases/download/cuda-core-v0.6.0/cuda-python-cuda-core-v0.6.0.tar.gz \ + | sha256sum + ``` + +4. **Host dependencies**: Ensure all headers needed at build time are + listed. For example, v0.6.0 added a Cython C++ dependency on + `nvrtc.h`, requiring `cuda-nvrtc-dev` to be added to both `host` + requirements and `ignore_run_exports_from`. + +5. **Test commands and descriptions**: Update any import paths or + descriptions that changed (e.g. `cuda.core.experimental` -> + `cuda.core`). + +### Open a PR + +```bash +git add recipe/meta.yaml +git commit -m "Update cuda-core to 0.6.0" +git push update-v0.6.0 + +gh pr create \ + --repo conda-forge/cuda-core-feedstock \ + --head :update-v0.6.0 \ + --title "Update cuda-core to 0.6.0" \ + --body "Update cuda-core to version 0.6.0." +``` + +The feedstock CI (Azure Pipelines) triggers automatically on the PR. +Monitor it for build failures — common issues include missing +build-time header dependencies (see host dependencies above). + +--- + +## Post-release QA + +*TBD* + +--- + +## Finalize the announcement update + +*TBD* + +--- + +## Send out the announcement internally + +*TBD* + +--- + +## Send out the announcement externally (GitHub Release -> Announcement) + +*TBD* From 925f39972b5d7c3000025da3f783ca09a83adb80 Mon Sep 17 00:00:00 2001 From: Andy Jost Date: Mon, 23 Feb 2026 14:22:43 -0800 Subject: [PATCH 2/2] Address review feedback on RELEASE.md - Remove internal nvbug link, keep example text - Condense dependency check guidance - Remove stale note about docs build failing on tag push - Clarify test verification uses checked-out repo - Document three conda-forge approaches (bot auto, bot request, manual) Co-authored-by: Cursor --- .github/ISSUE_TEMPLATE/release_checklist.yml | 2 +- .github/{RELEASE.md => RELEASE-core.md} | 123 +++++++++++-------- 2 files changed, 72 insertions(+), 53 deletions(-) rename .github/{RELEASE.md => RELEASE-core.md} (63%) diff --git a/.github/ISSUE_TEMPLATE/release_checklist.yml b/.github/ISSUE_TEMPLATE/release_checklist.yml index cca1c0d077..f7307fbe92 100644 --- a/.github/ISSUE_TEMPLATE/release_checklist.yml +++ b/.github/ISSUE_TEMPLATE/release_checklist.yml @@ -10,7 +10,7 @@ body: - type: markdown attributes: value: | - This checklist is for cuda-core releases as well as cuda-bindings patches. Please go through this checklist and ensure all tasks are completed. See [RELEASE.md](../RELEASE.md) for detailed guidance on each step. + This checklist is for cuda-core releases as well as cuda-bindings patches. Please go through this checklist and ensure all tasks are completed. See [RELEASE-core.md](../RELEASE-core.md) for detailed guidance on each step (cuda.core). - type: checkboxes id: subpackage-tasks diff --git a/.github/RELEASE.md b/.github/RELEASE-core.md similarity index 63% rename from .github/RELEASE.md rename to .github/RELEASE-core.md index 165a83edb8..531f56f676 100644 --- a/.github/RELEASE.md +++ b/.github/RELEASE-core.md @@ -1,9 +1,15 @@ -# Release Process +# cuda.core Release Process -This document provides detailed guidance for each step of the +This document covers the `cuda.core` release process. For other packages: +`cuda-bindings` and `cuda-python` involve a private repository and are not +documented here; `cuda-pathfinder` is largely automated by the +[release-cuda-pathfinder.yml](workflows/release-cuda-pathfinder.yml) +workflow. + +Each section below provides detailed guidance for a step in the [Release Checklist](ISSUE_TEMPLATE/release_checklist.yml). To start a release, create a new issue from that template and work through it item by item, referring back here as needed. @@ -12,12 +18,12 @@ item, referring back here as needed. ## File an internal nvbug -Create an nvbug from the SWQA template to request pre-release validation. -To find the template, search for a previous release's nvbug (e.g. by -title "Release of cuda.core") and create a new bug from the same template. +Create an nvbug to request that SWQA begin post-release validation. Issues +identified by that process are typically addressed in a patch release. To find +the template, search for a previous release's nvbug (e.g. by title "Release of +cuda.core") and create a new bug from the same template. -Example (from the cuda.core v0.6.0 release, -[nvbug 5910741](https://nvbugspro.nvidia.com/bug/5910741)): +Example: > **Title:** Release of cuda.core v0.6.0 > @@ -48,28 +54,15 @@ Example (from the cuda.core v0.6.0 release, > - PyPI wheel upload > - Post-release validation -**How to determine the SW combinations:** - -- **cuda.core version**: The version being released. -- **cuda.bindings, CTK, and CUDA driver versions**: Check with the release owner. - -Update the version, SW combinations, and platforms as appropriate for each -release. +Update the version, SW combinations (check with the release owner), and +platforms as appropriate for each release. --- ## Check (or update if needed) the dependency requirements -Review `cuda_core/pyproject.toml` and verify the following are current: - -- `requires-python` — supported Python version range -- `dependencies` — runtime dependencies (e.g. `numpy`) -- `[project.optional-dependencies]` — `cuda-bindings` version pins for - `cu12` / `cu13` extras -- `[build-system] requires` — Cython and setuptools version pins -- `[dependency-groups]` — test dependencies (`ml-dtypes`, `cupy`, - `cuda-toolkit` version pins) -- Python version classifiers in `[project]` +Review `cuda_core/pyproject.toml` and verify that all dependency +requirements are current. --- @@ -120,8 +113,6 @@ git push origin cuda-core-v0.6.0 Pushing the tag triggers a CI run automatically. Monitor it in the **Actions** tab on GitHub. -- **The docs build is expected to fail** on tag-triggered runs. This is - normal — docs are built during the release workflow instead. - **All CI tests should succeed.** If any fail, investigate and rerun as needed. - Note the **run ID** of the successful tag-triggered run. The release @@ -149,10 +140,10 @@ publish to PyPI. [`ci/versions.yml`](../ci/versions.yml) (e.g. `13.1.1`) - **Which wheel index to publish to**: `testpypi` -2. Wait for the workflow to complete. The docs build step will fail on - forks — this is expected and does not block the wheel upload. +2. Wait for the workflow to complete. -3. Verify the TestPyPI upload by installing and running tests locally: +3. Verify the TestPyPI upload by installing and running tests from a + checked-out copy of the repository: ```bash pip install -i https://test.pypi.org/simple/ \ @@ -177,27 +168,43 @@ pip install cuda-core==0.6.0 ## Update the conda recipe & release conda packages The conda-forge feedstock builds from the GitHub Release source archive -(not from PyPI). The bot (`regro-cf-autotick-bot`) does not always pick up -new releases automatically, so you may need to open the PR manually. +(not from PyPI). There are three approaches to updating the feedstock, +from least effort to most control. -### Fork and clone the feedstock +### Approach A: Wait for the bot -```bash -gh repo fork conda-forge/cuda-core-feedstock --clone -cd cuda-core-feedstock -``` +The `regro-cf-autotick-bot` periodically scans for new releases and opens +a PR automatically. If nothing has changed in the build requirements, the +bot's PR may be sufficient — review it and ask a feedstock maintainer +to merge. However, the bot only +updates the version and sha256. If build dependencies, import paths, or +other recipe fields have changed, the bot's PR will be incomplete and CI +will fail. + +### Approach B: Request a bot update + +If the bot hasn't opened a PR, you can request one explicitly. Go to the +feedstock's Issues tab and create a new "Bot commands" issue: + +- **Title**: `@conda-forge-admin, please update version` +- **Body**: (leave empty) -Optional: Set up remotes so your fork is named after your GitHub username: +This triggers the bot to create a version-bump PR. As with approach A, +review the PR and push additional fixes if needed. + +### Approach C: Manual PR + +For full control — or when the bot's PR needs extensive fixes — open a +PR manually from a fork. + +**Fork and clone** (one-time setup): ```bash -git remote rename origin -git remote add origin https://github.com/conda-forge/cuda-core-feedstock.git -git fetch origin +gh repo fork conda-forge/cuda-core-feedstock --clone +cd cuda-core-feedstock ``` -### Update `recipe/meta.yaml` - -Create a branch and edit `recipe/meta.yaml`: +**Create a branch and edit `recipe/meta.yaml`:** ```bash git checkout -b update-v0.6.0 origin/main @@ -215,16 +222,16 @@ Update the following fields: | sha256sum ``` -4. **Host dependencies**: Ensure all headers needed at build time are - listed. For example, v0.6.0 added a Cython C++ dependency on - `nvrtc.h`, requiring `cuda-nvrtc-dev` to be added to both `host` - requirements and `ignore_run_exports_from`. +4. **Host dependencies**: Ensure all build-time dependencies are listed. + For example, v0.6.0 added a Cython C++ dependency on `nvrtc.h`, + requiring `cuda-nvrtc-dev` in both `host` requirements and + `ignore_run_exports_from`. 5. **Test commands and descriptions**: Update any import paths or descriptions that changed (e.g. `cuda.core.experimental` -> `cuda.core`). -### Open a PR +**Open a PR:** ```bash git add recipe/meta.yaml @@ -238,9 +245,12 @@ gh pr create \ --body "Update cuda-core to version 0.6.0." ``` +### Notes + The feedstock CI (Azure Pipelines) triggers automatically on the PR. -Monitor it for build failures — common issues include missing -build-time header dependencies (see host dependencies above). +Monitor it for build failures — common issues include missing build-time +header dependencies. Feedstock maintainers (listed in +`recipe/meta.yaml` under `extra.recipe-maintainers`) can merge the PR. --- @@ -252,13 +262,22 @@ build-time header dependencies (see host dependencies above). ## Finalize the announcement update -*TBD* +The release workflow creates a draft GitHub Release. To publish it: + +1. Go to the repository on GitHub, click **Tags**, then switch to the + **Releases** tab. +2. Find the draft release for the new tag and click **Edit**. +3. Copy the body from a previous release as a starting point. It + typically links to the release notes in the documentation (e.g. + `https://nvidia.github.io/cuda-python/cuda-core/latest/release/0.6.0-notes.html`). +4. Update the link and any version references, then click + **Publish release**. --- ## Send out the announcement internally -*TBD* +The release owner will prepare and send the announcement. ---