DOC: Clarify third-party fork conventions and de-duplicate update docs

Document the divergent/pruned fork type (vxl/VNL) where <sha7> is the
overlay-tip commit and <version> is master, and require branch-only overlay
anchors (a same-named branch and tag make the ref ambiguous and break
update-third-party.bash).

Make ThirdPartyForkConventions.md the single source of truth for fork naming
and updating_third_party.md the source for procedure; cross-link them and drop
the stale for/itk naming restatements. Route to both from AGENTS.md and fix the
VNL README link that pointed at a nonexistent Maintenance/UpdatingThirdParty.md.

Author: hjmjohnson

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
 

Documentation/Maintenance/ThirdPartyForkConventions.md

@@ -5,7 +5,11 @@ 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.
+
+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 one
 convention.
@@ -25,13 +29,39 @@ Each overlay branch is named `for/itk-<project>-<version>-<sha7>` 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.
+- `<sha7>` is the 7-character commit hash identifying the overlay's base
+  (see the two fork types below).
 
 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.
 
+### Two fork types
+
+| Type | Examples | `<version>` | `<sha7>` |
+|------|----------|-------------|----------|
+| Release-tracking | `eigen`, `dcmtk` | upstream release (`3.7.0`) | the upstream release-tag commit |
+| Divergent / pruned | `vxl` (VNL) | `master` | the overlay-tip commit on the fork |
+
+A release-tracking fork rebases a thin overlay onto each new upstream release,
+so `<sha7>` names the upstream commit the overlay sits on. A divergent fork has
+no upstream release to track — the `vxl` fork, for instance, is a pruned
+numerics-only subset whose only stable identifier is its own overlay tip — so
+`<version>` is `master` and `<sha7>` is the overlay-tip commit on the fork. The
+fork's `welcome` README states which type it is so the `<sha7>` provenance is
+unambiguous.
+
+### 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
@@ -43,4 +73,7 @@ reproducible:
 
 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.
+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

Documentation/docs/contributing/updating_third_party.md

@@ -10,15 +10,21 @@ 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 `for/itk-<project>-<version>-<sha7>` overlay branch
+naming, 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
@@ -29,10 +35,10 @@ Here's an example of updating the `DoubleConversion` project from tag 1.1.6 to
 
 ```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
+git checkout -b for/itk-doubleconversion-3.0.0-<sha7> for/itk-doubleconversion-1.1.6-<sha7>
+git rebase --onto doubleconversion-3.0.0 doubleconversion-1.1.6
+git push origin for/itk-doubleconversion-3.0.0-<sha7>
 ```
 
 Now import into ITK
@@ -92,12 +98,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 +115,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-<sha7>   # see Third-Party Fork Conventions
+git push --set-upstream insight for/itk-foo-3.0.0-<sha7>
 ```
 
 Making the initial import involves filling out the project's
@@ -153,5 +159,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

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.