DOC: Clarify vendored third-party fork conventions#6432
Conversation
github-actions
Bot
added
type:Documentation
This comment was marked as resolved.
This comment was marked as resolved.
hjmjohnson
force-pushed
the
doc-thirdparty-fork-conventions
branch
from
b836a3b to
1f722cf
Compare
|
Addressed the greptile finding in 1f722cf: the "Updating a Project" example now uses the |
dzenanz
left a comment
dzenanz
left a comment
There was a problem hiding this comment.
I had a quick look and have no objections. I would prefer if Brad made a bit closer review.
blowekamp
left a comment
blowekamp
left a comment
There was a problem hiding this comment.
Two suggestions:
minimize the docs on managing a fork here, rely on the welcome docs
For the two styles of forks, have the branch name convention be noticeably different.
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.
hjmjohnson
force-pushed
the
doc-thirdparty-fork-conventions
branch
from
1f722cf to
4fd6584
Compare
blowekamp
left a comment
blowekamp
left a comment
There was a problem hiding this comment.
Thank you for the updates. This PR looks good to me. Has the VNL fork be updated to follow this convention now?
3 participants
Documentation-only: clarifies ITK's vendored third-party fork conventions and de-duplicates the two overlapping update docs. Prompted by @blowekamp's review on #6431, which flagged that the fork procedure was unclear about branch/tag anchoring and SHA provenance.
What changed
Documentation/Maintenance/ThirdPartyForkConventions.md— adds a two fork types table: release-tracking forks (eigen, DCMTK) use the upstream release + upstream-tag SHA; divergent/pruned forks (vxl/VNL) track no upstream release, so<version>ismasterand<sha7>is the overlay-tip commit. Adds a branches, never tags rule: a same-named branch and tag make a ref ambiguous (warning: refname is ambiguous) and breakupdate-third-party.bash.Documentation/docs/contributing/updating_third_party.md— removes the stalefor/itksingle-branch naming (which conflicted with thefor/itk-<project>-<version>-<sha7>convention) and defers all naming to ThirdPartyForkConventions.md. The two docs are now cross-linked: conventions = naming/structure, this doc = procedure.AGENTS.md— routes agents to both docs when updating a vendored dependency.Modules/ThirdParty/VNL/README.md— fixes a dead link that pointed at a nonexistentDocumentation/Maintenance/UpdatingThirdParty.md; now links the realupdating_third_party.mdand the conventions doc.Scope / testing
Documentation only — no code, no build/test impact.
pre-commit run --all-filespasses. Relative links in the VNL README verified to resolve.