InsightSoftwareConsortium · hjmjohnson · Jun 11, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -25,6 +25,7 @@ the minimum set for the task at hand.
 | Creating a **COMP:** commit | [git-commits.md](./Documentation/AI/git-commits.md), [compiler-cautions.md](./Documentation/AI/compiler-cautions.md) |
 | Commit or PR attribution | [attribution.md](./Documentation/AI/attribution.md) |
 | Opening or updating a pull request | [pull-requests.md](./Documentation/AI/pull-requests.md), [attribution.md](./Documentation/AI/attribution.md) |
+| Updating a vendored ThirdParty dependency or its fork (eigen, DCMTK, VNL/vxl) | [ThirdPartyForkConventions.md](./Documentation/Maintenance/ThirdPartyForkConventions.md), [updating_third_party.md](./Documentation/docs/contributing/updating_third_party.md) |
 
 ## Critical Pitfalls
 

diff --git a/Documentation/Maintenance/ThirdPartyForkConventions.md b/Documentation/Maintenance/ThirdPartyForkConventions.md
@@ -5,10 +5,14 @@ Several ITK third-party dependencies are vendored from a fork hosted under the
 organization (for example
 [eigen](https://github.com/InsightSoftwareConsortium/eigen) and
 [DCMTK](https://github.com/InsightSoftwareConsortium/DCMTK)). Each fork carries
-a small overlay of ITK-specific patches on top of an upstream release.
+an overlay of ITK-specific patches on top of an upstream baseline.
 
-To keep these forks predictable and self-documenting, all ITK forks follow one
-convention.
+This document defines how those forks are *named and structured*. For the
+step-by-step procedure to update or initially port a dependency, see
+[Updating Third Party Projects].
+
+To keep these forks predictable and self-documenting, all ITK forks follow the
+conventions below.
 
 ## Default branch: `welcome`
 
@@ -19,28 +23,58 @@ Because GitHub renders the default branch's README on the repository landing
 page, a visitor immediately sees how the fork is maintained instead of a stale
 upstream description.
 
-## Branch naming: `for/itk-<project>-<version>-<sha7>`
+## Branch naming
+
+ITK forks come in two types, and the overlay branch name's middle field tells
+you which:
+
+- **Release-anchored** — a thin overlay rebased onto a fixed upstream release:
+  `for/itk-<project>-<version>-<shaN>`
+  (e.g. `for/itk-eigen-5.0.1-bc3b39870`, `for/itk-dcmtk-3.7.0-ccfd10b`).
+- **Branch-anchored** — an overlay tracking an upstream branch tip with no
+  release to pin: `for/itk-<project>-<upstream-branch>-<shaN>`
+  (e.g. `for/itk-vxl-master-272c3f1`).
 
-Each overlay branch is named `for/itk-<project>-<version>-<sha7>` where:
+where:
 
-- `<project>` is the forked project (e.g. `eigen`, `dcmtk`),
-- `<version>` is the upstream release the overlay is built on (e.g. `3.7.0`),
-- `<sha7>` is the 7-character commit hash of that upstream release tag.
+- `<project>` is the forked project (e.g. `eigen`, `dcmtk`, `vxl`),
+- the middle field is a release `<version>` (e.g. `5.0.1`) for release-anchored,
+  or an upstream `<branch>` name (e.g. `master`) for branch-anchored,
+- `<shaN>` is the abbreviated commit hash (at least 7 characters) of the
+  overlay's base: the upstream release-tag commit for release-anchored, or the
+  overlay-tip commit for branch-anchored.
 
-For example, `for/itk-dcmtk-3.7.0-ccfd10b` carries the ITK overlay on top of
-upstream DCMTK tag `DCMTK-3.7.0` (commit `ccfd10b`). Older non-conforming
-branches are retained for historical reference but are no longer the update
-target.
+For example, `for/itk-dcmtk-3.7.0-ccfd10b` carries the ITK overlay on upstream
+DCMTK tag `DCMTK-3.7.0` (commit `ccfd10b`), while `for/itk-vxl-master-272c3f1`
+is the `vxl` overlay tip — a pruned numerics-only subset with no upstream
+release to track. The fork's `welcome` README states which type it is. Older
+non-conforming branches are retained for historical reference but are no longer
+the update target.
+
+### Anchor overlay commits with branches, never tags
+
+Each overlay commit ITK may pin is anchored by a **branch**; do **not** also
+create a tag with the same name. A ref that exists as both a branch and a tag
+(e.g. a branch and a tag both named `for/itk-vxl-master-fd75e8b`) is ambiguous:
+`git checkout`/`git fetch` of that name emits `warning: refname is ambiguous`
+and may resolve the wrong object, breaking `update-third-party.bash`. Protect
+each anchor branch against deletion and force-push so the pinned commit stays
+reachable as the moving branch advances.
 
 ## Pinning the fork in ITK
 
-ITK pins a specific overlay commit, not a branch name, so the build is
-reproducible:
+Each module records the overlay ref it consumes in its update script:
 
-- `eigen` is consumed through `Modules/ThirdParty/Eigen3/UpdateFromUpstream.sh`.
-- `DCMTK` is pinned by `DCMTK_GIT_TAG` in
+- `eigen` records the overlay branch in `tag=` in
+  `Modules/ThirdParty/Eigen3/UpdateFromUpstream.sh`.
+- `DCMTK` pins an immutable commit via `DCMTK_GIT_TAG` in
   `Modules/ThirdParty/DCMTK/DCMTKGitTag.cmake`.
 
-When updating, the per-fork `welcome` branch is the authoritative, current
-description of the procedure; follow it, then update the corresponding pin in
-ITK and refresh the patch-list comment.
+Either way the overlay branch name embeds the upstream version (or branch) and
+base `<shaN>`, so an imported overlay's provenance is explicit. When updating,
+the per-fork `welcome` branch is the authoritative, current description of the
+procedure; follow it, then update the corresponding ref in ITK and refresh the
+patch-list comment. The general update and porting steps are in
+[Updating Third Party Projects].
+
+[Updating Third Party Projects]: ../docs/contributing/updating_third_party.md
diff --git a/Documentation/docs/contributing/updating_third_party.md b/Documentation/docs/contributing/updating_third_party.md
@@ -10,36 +10,35 @@ patches to the third party projects are tracked externally and available for
 Any updates to projects not listed there should first convert over to this
 framework.
 
+This document covers the *procedure*. How each fork is named and structured
+(the `welcome` branch, the two overlay branch-naming grammars for the two fork
+types, and the branches-not-tags anchor rule) is defined
+in [Third-Party Fork Conventions]. Follow that document for naming; follow this
+one for the mechanics.
+
 Updating a Project
 ------------------
 
 Once converted, a project should be updated by applying patches to the
 repository specified in its `UpdateFromUpstream.sh` script. Once the upstream
 changes are merged, pulling the changes involves running the
 `UpdateFromUpstream.sh` script. This will update the local copy of the project
-to the version specified in `UpdateFromUpstream.sh` (usually a `for/foo`
-branch, like `for/itk` for example, but may be `main` or any other Git
+to the reference specified in `UpdateFromUpstream.sh` (an overlay branch named
+per [Third-Party Fork Conventions], but may be `main` or any other Git
 reference) and merge it into the main tree.
 
 This requires a Git 2.5 or higher due the `worktree` tool being used to
 simplify the availability of the commits to the main checkout.
 
-Here's an example of updating the `DoubleConversion` project from tag 1.1.6 to
-3.0.0, starting with updating the third-party repo
-
-```bash
-cd ./Modules/ThirdParty/DoubleConversion
-git checkout for/itk
-git fetch origin
-git rebase --onto doubleconversion-1.1.6 doubleconversion-3.0.0
-git push
-```
-
-Now import into ITK
+For an ITK-overlay fork (for example
+[eigen](https://github.com/InsightSoftwareConsortium/eigen)), the authoritative,
+current step-by-step for advancing the overlay branch lives in that fork's
+`welcome` branch README; follow it there rather than a copy duplicated here.
+Once the overlay branch has been advanced, import it into ITK:
 
 ```bash
-cd ./Modules/ThirdParty/twisted
-git checkout -b update_doubleconversion
+cd ./Modules/ThirdParty/Eigen3
+git checkout -b update_eigen
 ./UpdateFromUpstream.sh
 ```
 
@@ -92,12 +91,12 @@ to track it. If the upstream project does not use Git, it should be imported
 into Git (there may be existing conversions available on GitHub already). The
 project's description should indicate where the source repository lives.
 
-Once a mirror of the project is created, a branch named `for/foo` should be
-created where patches for the `foo` project will be applied (i.e., `for/itk`
-for ITK's patches to the project). Usually, changes to the build system, the
-source code for mangling, the addition of `.gitattributes` files, and other
-changes belong here. Functional changes should be submitted upstream (but may
-still be tracked so that they may be used).
+Once a mirror of the project is created, an overlay branch named per
+[Third-Party Fork Conventions] should be created where patches for the project
+will be applied. Usually, changes to the build system, the source code for
+mangling, the addition of `.gitattributes` files, and other changes belong
+here. Functional changes should be submitted upstream (but may still be tracked
+so that they may be used).
 
 The basic steps to import a project `foo` based on the tag `foo-3.0.0` looks
 like this:
@@ -109,8 +108,8 @@ git remote add insight git@github.com:InsightSoftwareConsortium/ITK.git:Modules/
 git push -u insight
 git push -u insight --tags
 git checkout foo-3.0.0
-git checkout -b for/itk
-git push --set-upstream insight for/itk
+git checkout -b for/itk-foo-3.0.0-<shaN>   # see Third-Party Fork Conventions
+git push --set-upstream insight for/itk-foo-3.0.0-<shaN>
 ```
 
 Making the initial import involves filling out the project's
@@ -153,5 +152,6 @@ if necessary.
 
 
 
+[Third-Party Fork Conventions]: https://github.com/InsightSoftwareConsortium/ITK/blob/main/Documentation/Maintenance/ThirdPartyForkConventions.md
 [update-third-party.bash]: https://github.com/InsightSoftwareConsortium/ITK/blob/main/Utilities/Maintenance/update-third-party.bash
 [update-third-party skill]: https://github.com/InsightSoftwareConsortium/ITK/blob/main/.github/skills/update-third-party/SKILL.md
diff --git a/Modules/ThirdParty/VNL/README.md b/Modules/ThirdParty/VNL/README.md
@@ -6,4 +6,7 @@ Documentation about the library can be found at
 
   https://vxl.github.io/
 
-See [UpdatingThirdParty.md](https://github.com/InsightSoftwareConsortium/ITK/blob/master/Documentation/Maintenance/UpdatingThirdParty.md) for details and instructions to update from upstream.
+See [Updating Third Party Projects](../../../Documentation/docs/contributing/updating_third_party.md)
+for instructions to update from upstream, and
+[Third-Party Fork Conventions](../../../Documentation/Maintenance/ThirdPartyForkConventions.md)
+for the fork branch-naming conventions.