diff --git a/.github/skills/update-third-party/SKILL.md b/.github/skills/update-third-party/SKILL.md new file mode 100644 index 00000000000..c4e69522219 --- /dev/null +++ b/.github/skills/update-third-party/SKILL.md @@ -0,0 +1,142 @@ +--- +name: update-third-party +description: 'Update an ITK third-party library to a new version. Use when: bumping a vendored dependency version, updating ThirdParty module, running UpdateFromUpstream.sh. Creates a new branch with the tag-update commit and runs the extraction script.' +argument-hint: 'Which third-party library to update and the new version/tag' +--- + +# Update ITK Third-Party Library + +Creates a new git branch with the commits needed to update a vendored third-party library in `Modules/ThirdParty/`. + +## When to Use + +- Updating a third-party library (e.g., JPEG, ZLIB, HDF5, GoogleTest) to a new upstream version +- User says "update to " + +## Inputs + +Gather these from the user before starting: + +| Input | Example | Required | +|-------|---------|----------| +| Library name | `JPEG`, `ZLIB`, `GoogleTest` | Yes | +| New version/tag | `3.1.0`, `v1.18.0`, commit hash | Yes | +| Branch name | `update_jpeg` | No (auto-generated) | + +## Procedure + +### 1. Locate the Update Script + +Find the module's update script in `Modules/ThirdParty//`. The script name varies: +- Most modules: `UpdateFromUpstream.sh` +- DoubleConversion: `UpdateDoubleConversionFromGoogle.sh` + +If there is no update script it is an error! STOP. + +Read the script to understand the module's configuration (`name`, `tag`, `repo`, `paths`, `extract_source` function). + +### 2. Create a New Branch + +```bash +git fetch origin +git checkout -b update_ origin/main +``` + +Replace `` with a short snake_case identifier (e.g., `update_jpeg`, `update_zlib`, `update_hdf5`). If the user specifies a branch name, use that instead. + +### 3. Update the Tag in the Update Script + +Edit the `readonly tag="..."` line in the update script to the new version. Only change the `tag` value — nothing else. + +Commit this change: + +```bash +git add Modules/ThirdParty//.sh +git commit -m "ENH: Update to " +``` + +The commit message body may optionally include links to upstream release notes or changelog. + +### 4. Run the Update Script + +```bash +./Modules/ThirdParty//.sh +``` + +This script (powered by `Utilities/Maintenance/update-third-party.bash`): +1. Clones the upstream repository +2. Checks out the specified tag +3. Runs `extract_source()` to prepare a clean subtree +4. Finds the previous import commit via git history +5. Merges the upstream changes into `Modules/ThirdParty//src/` +6. Creates a merge commit. + + +### 5. Resolve Any Merge Conflicts + +If there are merge conflicts during the extraction step, the script will pause and prompt you to resolve them in the `work/` directory. + +Inspect the git history for local changes, and determine ITK's local changes, and the upstream changes. Use your judgment to resolve the conflicts, then stage and commit the resolved files. + +```bash +git add +git commit +``` + + +### 6. Handle Post-Update Steps (if needed) + +Some modules require additional work after extraction: + +- **Mangling**: If the module uses symbol mangling, you may need to regenerate the mangled headers. This is common for C libraries like JPEG and ZLIB. Follow the instructions in the module's `src/` directory (e.g., `src/itkjpeg/src/itk_jpeg_mangle.h.in`). +- **Build fixes**: If the upstream CMake changed significantly, the module's outer `CMakeLists.txt` may need updates. Commit these as separate `COMP:` or `ENH:` commits. + + +### 7. Verify the Result + +Verify the commit history: + +```bash +git log --oneline -3 +git diff HEAD~2..HEAD --stat +``` + +### 8. Build and Test the changes locally + +Build ITK with the updated module to ensure there are no build errors. +### 9. Push and Create PR + +The branch is ready for pushing and PR creation. The PR should target `main`. + +Determine which remote is the user's fork: + +```bash +git remote -v +``` + +Push the branch to the user's fork: + +```bash +git push update_ +``` + +Use the GitHub MCP to create a PR for `main` with a title like "ENH: Update to ". The PR description should include: +- A summary of the update +- Links to upstream release notes or changelog +- Any relevant notes about the update (e.g., if there were significant merge conflicts or build +fixes needed) +- That the commit was generated by the `update-third-party` skill + + + +## Troubleshooting + +| Problem | Solution | +|---------|----------| +| `No previous import commit found` | The module may use `exact_tree_match=false`; check the script | +| Merge conflicts during extraction | Resolve conflicts under the ThridParty directory +## Reference + +- Official documentation: [Updating Third Party Projects](../../../Documentation/docs/contributing/updating_third_party.md) +- Master update script: [Utilities/Maintenance/update-third-party.bash](../../../Utilities/Maintenance/update-third-party.bash) +- All third-party modules: [Modules/ThirdParty/](../../../Modules/ThirdParty/) diff --git a/Documentation/docs/contributing/updating_third_party.md b/Documentation/docs/contributing/updating_third_party.md index 8fa21892ccd..39607c2e4fd 100644 --- a/Documentation/docs/contributing/updating_third_party.md +++ b/Documentation/docs/contributing/updating_third_party.md @@ -45,6 +45,43 @@ git checkout -b update_doubleconversion Now you can review the change and make a merge request from the branch as normal. +Using the Automated Skill (VS Code with GitHub Copilot) +-------------------------------------------------------- + +For VS Code users with GitHub Copilot, an automated [update-third-party skill] +streamlines the update process. The skill automates the workflow described above: +creating a branch, updating the tag, running the extraction script, resolving +conflicts, and creating a pull request. To create a pull request, the GitHub MCP is recommended. + +To use the skill, invoke it via Copilot by providing the library name and +version tag: + +``` +@workspace /update-third-party +``` + +For example: + +``` +@workspace /update-third-party PNG v1.6.54 +``` + +See the skill for details of the steps. + +The steps may involve resolving conflicts and updating name mangling. These steps should be carefully reviewed and verified. + +This is particularly useful for routine updates where the upstream changes are +straightforward. The skill follows ITK's conventions for commit messages, +branch naming, and PR descriptions. + +**When to use the skill:** +- Updating to a new tagged release of an existing third-party library +- The library already has a working `UpdateFromUpstream.sh` script +- You want to automate the mechanical aspects of the update process + + +See the [update-third-party skill] documentation for complete details. + Porting a Project ----------------- @@ -117,3 +154,4 @@ if necessary. [update-third-party.bash]: https://github.com/InsightSoftwareConsortium/ITK/blob/main/Utilities/Maintenance/update-third-party.bash +[update-third-party skill]: https://github.com/InsightSoftwareConsortium/ITK/blob/main/.github/skills/update-third-party/SKILL.md