diff --git a/.agents/skills/update-dependency-version/SKILL.md b/.agents/skills/update-dependency-version/SKILL.md new file mode 100644 index 00000000..2814f8a1 --- /dev/null +++ b/.agents/skills/update-dependency-version/SKILL.md @@ -0,0 +1,148 @@ +--- +name: update-dependency-version +description: Update any dependency version in rapids-cmake/cpm/versions.json and open a PR +--- + +## What I do + +Update any package entry in `rapids-cmake/cpm/versions.json` to a new commit, then create a PR following the established pattern. + +## Schemas + +Two schemas exist in `versions.json`. Detect which one the target package uses before editing. + +**Git mode**: +```json +"": { + "version": "", + "git_url": "https://github.com//.git", + "git_tag": "" +} +``` +Update `version` and `git_tag`. Do not touch other fields (`git_shallow`, `always_download`, `source_subdir`, `proprietary_binary*`). + +**URL/tarball mode**: +```json +"CCCL": { + "version": "", + "url": "https://github.com///archive/.tar.gz", + "url_hash": "SHA256=" +} +``` +Update `version`, `url`, and `url_hash`. + +## Step-by-step procedure + +### 1. Read the current state + +``` +cat rapids-cmake/cpm/versions.json +``` + +Identify the target package's schema and record the old commit SHA (from `git_tag` or the commit SHA embedded in `url`) — needed for the PR comparison URL. + +### 2. Identify the GitHub repo + +Read `git_url` (git mode) or extract the org/repo from `url` (tarball mode). + +### 3. Resolve the new commit SHA + +**For a tag** (e.g. `v3.4.0`): +``` +gh api repos///git/ref/tags/v3.4.0 +``` +Check `.object.type` in the response: +- If `"commit"`: use `.object.sha` directly. +- If `"tag"`: dereference by calling `gh api repos///git/tags/` and check `.object.type` again. + +Repeat until `.object.type == "commit"`. Tags can be nested multiple levels deep (e.g. a tag pointing to a tag pointing to a commit). Always verify the final SHA exists as a commit: +``` +gh api repos///commits/ --jq '.sha' +``` +If the API returns a 422 error, the SHA is not a commit — keep dereferencing. + +**For a branch** (e.g. `branch/3.3.x` or `main`): +``` +gh api repos///commits/ --jq '.sha' +``` + +### 4. Compute SHA256 (URL/tarball mode only) + +Before downloading, confirm the commit SHA resolved in step 3 actually exists: +``` +gh api repos///commits/ --jq '.sha' +``` +If this returns a 422 error, stop and re-examine the tag dereference chain. + +``` +curl -sL https://github.com///archive/.tar.gz | sha256sum +``` + +Take the hex string (first field), prefix with `SHA256=`. + +### 5. Determine the new `version` string + +- For a tagged release: strip the leading `v` (e.g. `v3.4.0` → `"3.4.0"`) +- For a branch tip: check the source repo for the current version. Common locations include the project's top-level `CMakeLists.txt` (look for `project(... VERSION ...)`) or version header files. For example: + ``` + gh api repos///contents/CMakeLists.txt --jq '.content' | base64 -d | grep -i 'project(' | head -5 + ``` + Do NOT assume the version is unchanged from the previous entry in `versions.json` — the upstream repo may have bumped it. If the version cannot be determined from source files, ask the user. + +### 6. Edit `rapids-cmake/cpm/versions.json` + +Update only the fields appropriate for the schema (see Schemas section above). Do not change indentation, key order, or any other field. + +### 7. Verify the edit + +``` +rg -n '""' -A 6 rapids-cmake/cpm/versions.json +``` + +### 8. Create a branch and commit + +Use the following naming conventions for the PR title and commit message. Note: the pinned value in `versions.json` is always a commit hash, regardless of whether the user specified a tag or a branch. +- **User requested a specific tag** (e.g. `v3.4.0`): `"Update to "` (e.g. `"Update CCCL to 3.4.0"`) +- **User requested a branch tip** (e.g. `main`): `"Update to pre-release"` (e.g. `"Update CCCL to 3.4.0 pre-release"`) + +``` +git checkout -b update-- +git add rapids-cmake/cpm/versions.json +git commit -m "" +``` + +### 9. Push and open a PR + +``` +git push -u origin update-<package-lower>-<version> +``` + +PR body template (use the same `<title>` from step 8): +``` +## Description +This PR updates <package> to <title>. + +Comparison of <package> commits: https://github.com/<org>/<repo>/compare/<old-sha>...<new-sha> + +## Checklist +- [x] I am familiar with the [Contributing Guidelines](https://github.com/rapidsai/rapids-cmake/blob/HEAD/CONTRIBUTING.md). +- [x] New or existing tests cover these changes. +- [x] The documentation is up to date with these changes. +- [x] The `cmake-format.json` is up to date with these changes. +- [ ] I have added new files under rapids-cmake/ + - [ ] I have added include guards (`include_guard(GLOBAL)`) + - [ ] I have added the associated docs/ rst file and update the api.rst +``` + +Use `gh pr create` targeting `main`. + +### 10. Add labels to the PR + +After creating the PR, add labels using `gh pr edit`. Ask the user whether the change is breaking or non-breaking, then apply the appropriate labels: + +- **Non-breaking dependency update** (most common): `improvement` + `non-breaking` +- **Breaking dependency update**: `improvement` + `breaking` + +``` +gh pr edit <pr-number> --repo rapidsai/rapids-cmake --add-label "improvement" --add-label "non-breaking" +```