ENH: YYYYMMDD tweak version for between-tag gating (supersedes #6665)

[hjmjohnson]

Supersedes #6665 with the simpler design from its review discussion: the fourth (tweak) version component carries the YYYYMMDD (UTC) date of the most recent migration-inducing change, exported as ITK_VERSION_TWEAK / ITK_VERSION_FULL via ITKConfig.cmake, so downstream projects can gate at configure time between release tags — including during git bisect on untagged commits.

find_package(ITK REQUIRED)
if(ITK_VERSION_FULL VERSION_GREATER_EQUAL 6.0.0.20260715)
  set(BASELINE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/Baseline/post-change)
else()
  set(BASELINE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/Baseline/legacy)
endif()

Policy (documented in AGENTS.md, Documentation/AI/git-commits.md, and the migration-guide index): a change requiring a migration-guide entry or altering public API must bump ITK_VERSION_TWEAK; other key changes may. The value is never reset — release-tag version ordering expires it naturally, so no release-checklist steps are added.

Design notes vs #6665

• Answers "is ITK at least as new as the day X landed?" (ordering, day granularity) rather than per-change identity — the trade @blowekamp and @dzenanz endorsed in ENH: Add migration sentinels for between-tag downstream gating #6665.
• Drops all of ENH: Add migration sentinels for between-tag downstream gating #6665's apparatus: no sentinel files, no collector, no expiry tooling, no two-arm idiom (older ITK leaves ITK_VERSION_FULL unset → comparison false → legacy branch).
• The only tool is Utilities/Maintenance/BumpVersionTweak.py: sets the tweak to today's UTC date or a given date, refuses to move it backwards, idempotent.
• ccache-safe for free: itkConfigure.h's ITK_VERSION_STRING is major.minor only, so the tweak never reaches compiled headers.
• ITKConfigVersion.cmake.in gains the tweak in PACKAGE_VERSION; find_package(ITK 6.0.0 EXACT) still matches via an explicit three-component equality arm.
• Initial value 20260715 = date of the latest migration-guide change on main (fb2117c).

Verification

• Smoke-tested a 4-component project(VERSION) with itkVersion.cmake included: PROJECT_VERSION=6.0.0.20260715, VERSION_GREATER_EQUAL gates true/false correctly on either side of the date.
• BumpVersionTweak.py exercised: forward bump, backward-date rejection (exit 1), same-date no-op.
• pre-commit run --all-files clean.
• No new compiled code; CMake, docs, and one Python utility only.

[greptile-apps]

Greptile Summary

This PR adds a date-based tweak version component for between-tag migration gating. The main changes are:

• Export ITK_VERSION_TWEAK and ITK_VERSION_FULL through ITK CMake package files.
• Use the four-component version in the top-level CMake project metadata.
• Document the policy requiring tweak bumps for migration-guide and public API changes.
• Add Utilities/Maintenance/BumpVersionTweak.py to update the tweak date.

Confidence Score: 4/5

Mostly safe to merge after fixing the Python 3.10 helper failure.

The CMake versioning changes are small and consistent, and the maintenance helper issue is contained to one runtime compatibility path.

Utilities/Maintenance/BumpVersionTweak.py

T-Rex Logs

What T-Rex did

• I reproduced that BumpVersionTweak breaks on a Python 3.10‑like environment by confirming python3.10 is unavailable and python3 resolves to Python 3.11.6, and I ran a no-argument harness that uses a 3.10-like datetime module exposing timezone.utc to reproduce the failure, which raised AttributeError: module 'datetime' has no attribute 'UTC' at line 24.
• I verified end-to-end bump validation by running the bump-validation suite; the main transcript shows the run completed with exit code 0, with same-date, forward bump, and backward rejection evidence present and a CMake blocker observed.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
AGENTS.md	Adds the repository policy that migration-guide or public API changes must bump ITK_VERSION_TWEAK; no issues found.
CMake/ITKConfig.cmake.in	Exports ITK_VERSION_TWEAK and ITK_VERSION_FULL through ITKConfig.cmake; no issues found.
CMake/ITKConfigVersion.cmake.in	Extends PACKAGE_VERSION to four components while preserving exact matching for three-component version requests; no issues found.
CMake/itkVersion.cmake	Introduces the date-based tweak version component initialized to 20260715; no issues found.
CMakeLists.txt	Uses the full four-component version for the CMake project while retaining the three-component ITK_VERSION; no issues found.
Documentation/AI/git-commits.md	Documents the required tweak-version bump policy for migration and API changes; no issues found.
Documentation/docs/migration_guides/index.md	Documents downstream configure-time gating with ITK_VERSION_FULL; no issues found.
Utilities/Maintenance/BumpVersionTweak.py	Adds a helper to update ITK_VERSION_TWEAK, but the default UTC expression breaks on Python 3.10.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant Dev as Developer
participant Script as BumpVersionTweak.py
participant Version as CMake/itkVersion.cmake
participant Build as CMake project()
participant Config as ITKConfig.cmake
participant Downstream as Downstream CMake

Dev->>Script: run with YYYYMMDD or default UTC date
Script->>Version: update ITK_VERSION_TWEAK if date is not older
Build->>Version: include(itkVersion)
Build->>Build: project(ITK VERSION major.minor.patch.tweak)
Build->>Config: configure ITK_VERSION_TWEAK and ITK_VERSION_FULL
Downstream->>Config: find_package(ITK REQUIRED)
Downstream->>Downstream: compare ITK_VERSION_FULL for between-tag gating

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant Dev as Developer
participant Script as BumpVersionTweak.py
participant Version as CMake/itkVersion.cmake
participant Build as CMake project()
participant Config as ITKConfig.cmake
participant Downstream as Downstream CMake

Dev->>Script: run with YYYYMMDD or default UTC date
Script->>Version: update ITK_VERSION_TWEAK if date is not older
Build->>Version: include(itkVersion)
Build->>Build: project(ITK VERSION major.minor.patch.tweak)
Build->>Config: configure ITK_VERSION_TWEAK and ITK_VERSION_FULL
Downstream->>Config: find_package(ITK REQUIRED)
Downstream->>Downstream: compare ITK_VERSION_FULL for between-tag gating

Loading

_{Reviews (1): Last reviewed commit: "ENH: Add YYYYMMDD tweak version for betw..." | Re-trigger Greptile}

[greptile-apps]

Use supported UTC constant
datetime.UTC was added in Python 3.11, while ITK 6 documentation still states Python 3.10+ support for wrapping. On Python 3.10 this default argument is evaluated while building the parser, so running BumpVersionTweak.py without an explicit date raises AttributeError before it can bump the version; datetime.timezone.utc works across the supported range.

Context Used: AGENTS.md (source)

Artifacts

Repro: interpreter availability check showing python3.10 unavailable and python3 version

• Keeps the command output available without making the summary code-heavy.

Repro: Python 3.10 datetime.UTC absence simulation harness

• Contains supporting evidence from the run (text/x-python; charset=utf-8).

Stack trace captured during the T-Rex run

• Keeps the raw stack trace available without making the summary code-heavy.

_{Ran code and verified through T-Rex}

[hjmjohnson]

Only python 3.11+ are supported.