From 4fd65846b09182e9057aabe8036caf433dd33764 Mon Sep 17 00:00:00 2001 From: "Hans J. Johnson" Date: Thu, 11 Jun 2026 06:37:16 -0500 Subject: [PATCH] DOC: Clarify third-party fork conventions and de-duplicate update docs Document the divergent/pruned fork type (vxl/VNL) where is the overlay-tip commit and 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. --- AGENTS.md | 1 + .../Maintenance/ThirdPartyForkConventions.md | 72 ++++++++++++++----- .../docs/contributing/updating_third_party.md | 48 ++++++------- Modules/ThirdParty/VNL/README.md | 5 +- 4 files changed, 82 insertions(+), 44 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a25ab5296ee..175a595bc6d 100644 --- 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 index f5fb1c0ca88..f063c821c53 100644 --- 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---` +## 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---` + (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---` + (e.g. `for/itk-vxl-master-272c3f1`). -Each overlay branch is named `for/itk---` where: +where: -- `` is the forked project (e.g. `eigen`, `dcmtk`), -- `` is the upstream release the overlay is built on (e.g. `3.7.0`), -- `` is the 7-character commit hash of that upstream release tag. +- `` is the forked project (e.g. `eigen`, `dcmtk`, `vxl`), +- the middle field is a release `` (e.g. `5.0.1`) for release-anchored, + or an upstream `` name (e.g. `master`) for branch-anchored, +- `` 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 ``, 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 index 39607c2e4fd..aabb9d493cd 100644 --- a/Documentation/docs/contributing/updating_third_party.md +++ b/Documentation/docs/contributing/updating_third_party.md @@ -10,6 +10,12 @@ 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 ------------------ @@ -17,29 +23,22 @@ 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- # see Third-Party Fork Conventions +git push --set-upstream insight for/itk-foo-3.0.0- ``` 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 index 3aca6042edc..a51c80d471f 100644 --- 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.