update-third-party

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):

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/<NAME>/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.

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

• Official documentation: Updating Third Party Projects
• Master update script: Utilities/Maintenance/update-third-party.bash
• All third-party modules: Modules/ThirdParty/