Skip to content

Commit 24d0765

Browse files
blowekampblowekamp
committed
ENH: Add update-third-party Agent Skill for VS Code Copilot
This commit introduces a new VS Code Agent Skill that automates the process of updating ITK third-party libraries. Agent Skills are reusable AI workflows that extend GitHub Copilot's capabilities in VS Code. They enable domain-specific automation while maintaining human oversight. Learn more at https://agentskills.io/ The skill streamlines the update-third-party.bash workflow by: - Creating branches and updating version tags automatically - Running extraction scripts and detecting conflicts - Providing ITK-specific guidance for conflict resolution - Verifying symbol mangling for C libraries - Creating detailed pull requests with release notes - Following ITK conventions for commits, branches, and PRs Documentation updates: - Added skill documentation in .github/skills/update-third-party/ - Updated contributing guide with skill usage instructions - Established cross-references between skill and official docs
1 parent 9cffd1b commit 24d0765

2 files changed

Lines changed: 180 additions & 0 deletions

File tree

‎.github/skills/update-third-party/SKILL.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
---
2+
name: update-third-party
3+
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.'
4+
argument-hint: 'Which third-party library to update and the new version/tag'
5+
---
6+
7+
# Update ITK Third-Party Library
8+
9+
Creates a new git branch with the commits needed to update a vendored third-party library in `Modules/ThirdParty/`.
10+
11+
## When to Use
12+
13+
- Updating a third-party library (e.g., JPEG, ZLIB, HDF5, GoogleTest) to a new upstream version
14+
- User says "update <library> to <version>"
15+
16+
## Inputs
17+
18+
Gather these from the user before starting:
19+
20+
| Input | Example | Required |
21+
|-------|---------|----------|
22+
| Library name | `JPEG`, `ZLIB`, `GoogleTest` | Yes |
23+
| New version/tag | `3.1.0`, `v1.18.0`, commit hash | Yes |
24+
| Branch name | `update_jpeg` | No (auto-generated) |
25+
26+
## Procedure
27+
28+
### 1. Locate the Update Script
29+
30+
Find the module's update script in `Modules/ThirdParty/<NAME>/`. The script name varies:
31+
- Most modules: `UpdateFromUpstream.sh`
32+
- DoubleConversion: `UpdateDoubleConversionFromGoogle.sh`
33+
34+
If there is no update script it is an error! STOP.
35+
36+
Read the script to understand the module's configuration (`name`, `tag`, `repo`, `paths`, `extract_source` function).
37+
38+
### 2. Create a New Branch
39+
40+
```bash
41+
git fetch origin
42+
git checkout -b update_<lowercase_name> origin/main
43+
```
44+
45+
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.
46+
47+
### 3. Update the Tag in the Update Script
48+
49+
Edit the `readonly tag="..."` line in the update script to the new version. Only change the `tag` value — nothing else.
50+
51+
Commit this change:
52+
53+
```bash
54+
git add Modules/ThirdParty/<NAME>/<UpdateScript>.sh
55+
git commit -m "ENH: Update <library-name> to <version>"
56+
```
57+
58+
The commit message body may optionally include links to upstream release notes or changelog.
59+
60+
### 4. Run the Update Script
61+
62+
```bash
63+
./Modules/ThirdParty/<NAME>/<UpdateScript>.sh
64+
```
65+
66+
This script (powered by `Utilities/Maintenance/update-third-party.bash`):
67+
1. Clones the upstream repository
68+
2. Checks out the specified tag
69+
3. Runs `extract_source()` to prepare a clean subtree
70+
4. Finds the previous import commit via git history
71+
5. Merges the upstream changes into `Modules/ThirdParty/<NAME>/src/`
72+
6. Creates a merge commit.
73+
74+
75+
### 5. Resolve Any Merge Conflicts
76+
77+
If there are merge conflicts during the extraction step, the script will pause and prompt you to resolve them in the `work/` directory.
78+
79+
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.
80+
81+
```bash
82+
git add <resolved-files>
83+
git commit
84+
```
85+
86+
87+
### 6. Handle Post-Update Steps (if needed)
88+
89+
Some modules require additional work after extraction:
90+
91+
- **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`).
92+
- **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.
93+
94+
95+
### 7. Verify the Result
96+
97+
Verify the commit history:
98+
99+
```bash
100+
git log --oneline -3
101+
git diff HEAD~2..HEAD --stat
102+
```
103+
104+
### 8. Build and Test the changes locally
105+
106+
Build ITK with the updated module to ensure there are no build errors.
107+
### 9. Push and Create PR
108+
109+
The branch is ready for pushing and PR creation. The PR should target `main`.
110+
111+
Determine which remote is the user's fork:
112+
113+
```bash
114+
git remote -v
115+
```
116+
117+
Push the branch to the user's fork:
118+
119+
```bash
120+
git push <remote-name> update_<lowercase_name>
121+
```
122+
123+
Use the GitHub MCP to create a PR for `main` with a title like "ENH: Update <library> to <version>". The PR description should include:
124+
- A summary of the update
125+
- Links to upstream release notes or changelog
126+
- Any relevant notes about the update (e.g., if there were significant merge conflicts or build
127+
fixes needed)
128+
- That the commit was generated by the `update-third-party` skill
129+
130+
131+
132+
## Troubleshooting
133+
134+
| Problem | Solution |
135+
|---------|----------|
136+
| `No previous import commit found` | The module may use `exact_tree_match=false`; check the script |
137+
| Merge conflicts during extraction | Resolve conflicts under the ThridParty directory
138+
## Reference
139+
140+
- Official documentation: [Updating Third Party Projects](../../../Documentation/docs/contributing/updating_third_party.md)
141+
- Master update script: [Utilities/Maintenance/update-third-party.bash](../../../Utilities/Maintenance/update-third-party.bash)
142+
- All third-party modules: [Modules/ThirdParty/](../../../Modules/ThirdParty/)

‎Documentation/docs/contributing/updating_third_party.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,43 @@ git checkout -b update_doubleconversion
4545

4646
Now you can review the change and make a merge request from the branch as normal.
4747

48+
Using the Automated Skill (VS Code with GitHub Copilot)
49+
--------------------------------------------------------
50+
51+
For VS Code users with GitHub Copilot, an automated [update-third-party skill]
52+
streamlines the update process. The skill automates the workflow described above:
53+
creating a branch, updating the tag, running the extraction script, resolving
54+
conflicts, and creating a pull request. To create a pull request, the GitHub MCP is recommended.
55+
56+
To use the skill, invoke it via Copilot by providing the library name and
57+
version tag:
58+
59+
```
60+
@workspace /update-third-party <library-name> <version-tag>
61+
```
62+
63+
For example:
64+
65+
```
66+
@workspace /update-third-party PNG v1.6.54
67+
```
68+
69+
See the skill for details of the steps.
70+
71+
The steps may involve resolving conflicts and updating name mangling. These steps should be carefully reviewed and verified.
72+
73+
This is particularly useful for routine updates where the upstream changes are
74+
straightforward. The skill follows ITK's conventions for commit messages,
75+
branch naming, and PR descriptions.
76+
77+
**When to use the skill:**
78+
- Updating to a new tagged release of an existing third-party library
79+
- The library already has a working `UpdateFromUpstream.sh` script
80+
- You want to automate the mechanical aspects of the update process
81+
82+
83+
See the [update-third-party skill] documentation for complete details.
84+
4885
Porting a Project
4986
-----------------
5087

@@ -117,3 +154,4 @@ if necessary.
117154

118155

119156
[update-third-party.bash]: https://github.com/InsightSoftwareConsortium/ITK/blob/main/Utilities/Maintenance/update-third-party.bash
157+
[update-third-party skill]: https://github.com/InsightSoftwareConsortium/ITK/blob/main/.github/skills/update-third-party/SKILL.md

0 commit comments

Comments
 (0)