update-third-party

# 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 <library> to <version>" ## 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 ```bash 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: ```bash 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 ```bash ./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. ```bash 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: ```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 <remote-name> update_<lowercase_name> ``` Use the GitHub MCP to create a PR for `main` with a title like "ENH: Update <library> to <version>". 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/)