| 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/<NAME>/. 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
git fetch origin
git checkout -b update_<lowercase_name> origin/main
Replace <lowercase_name> 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:
git add Modules/ThirdParty/<NAME>/<UpdateScript>.sh
git commit -m "ENH: Update <library-name> to <version>"
The commit message body may optionally include links to upstream release notes or changelog.
4. Run the Update Script
./Modules/ThirdParty/<NAME>/<UpdateScript>.sh
This script (powered by Utilities/Maintenance/update-third-party.bash):
- Clones the upstream repository
- Checks out the specified tag
- Runs
extract_source() to prepare a clean subtree
- Finds the previous import commit via git history
- Merges the upstream changes into
Modules/ThirdParty/<NAME>/src/
- 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.
git add <resolved-files>
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:
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:
git remote -v
Push the branch to the user's fork:
git push <remote-name> update_<lowercase_name>
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
