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

More agent context in InsightSoftwareConsortium/ITK

3 other files this repository gives its agents.