ENH: Add migration sentinels for between-tag downstream gating

.github/workflows/migration-sentinels.yml

@@ -0,0 +1,28 @@
+name: Migration sentinels
+
+# A malformed sentinel is silently ignored by the CMake glob, so it would never
+# be published to downstream projects. Validate on every PR that touches one.
+
+on:
+  pull_request:
+    paths:
+      - 'CMake/MigrationSentinels/**'
+      - 'Utilities/Maintenance/MigrationSentinels.py'
+      - '.github/workflows/migration-sentinels.yml'
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - name: Validate migration sentinels
+        run: |
+          python3 Utilities/Maintenance/MigrationSentinels.py validate \
+            || {
+              echo "::error::A migration sentinel is malformed. See" \
+                   "Documentation/docs/contributing/migration_sentinels.md"
+              exit 1
+            }

CMake/ITKConfig.cmake.in

@@ -26,6 +26,12 @@ set(ITK_VERSION_MAJOR "@ITK_VERSION_MAJOR@")
 set(ITK_VERSION_MINOR "@ITK_VERSION_MINOR@")
 set(ITK_VERSION_PATCH "@ITK_VERSION_PATCH@")
 
+# Migration sentinels present in this ITK. Each entry asserts that one
+# downstream-visible change is in the code. Intended only for fine-grained
+# configure-time decisions between tagged releases; see
+# Documentation/docs/contributing/migration_sentinels.md
+set(ITK_MIGRATION_SENTINELS "@ITK_MIGRATION_SENTINELS@")
+
 # Remove all legacy code completely.
 set(ITK_LEGACY_REMOVE "@ITK_LEGACY_REMOVE@")
 

CMake/MigrationSentinels/ITK_MIGRATION_PR4704.md

@@ -0,0 +1 @@
+ENH: Finalize ITKv5 const function API change (PR #4704).

CMake/MigrationSentinels/ITK_MIGRATION_PR4715.md

@@ -0,0 +1 @@
+ENH: Remove ITKv4 compatibility support (PR #4715).

CMake/MigrationSentinels/ITK_MIGRATION_PR4729.md

@@ -0,0 +1 @@
+ENH: Remove features that were deprecated in ITKv5 (PR #4729).

CMake/MigrationSentinels/ITK_MIGRATION_PR4737.md

@@ -0,0 +1 @@
+Remove cxx aliases (PR #4737).

CMake/MigrationSentinels/ITK_MIGRATION_PR4744.md

@@ -0,0 +1 @@
+STYLE: Remove outdated maintenance scripts (PR #4744).

CMake/MigrationSentinels/ITK_MIGRATION_PR4925.md

@@ -0,0 +1 @@
+ENH: Let `PointSet::Clone()` do a "deep copy", instead of no copy at all (PR #4925).

CMake/MigrationSentinels/ITK_MIGRATION_PR5076.md

@@ -0,0 +1 @@
+DOC: Note migration guide replacing `CoordinateType` with `CoordRepType` (PR #5076).

CMake/MigrationSentinels/ITK_MIGRATION_PR5286.md

@@ -0,0 +1 @@
+ENH: Remove dummy VNLInstantiation library (PR #5286).

CMake/MigrationSentinels/ITK_MIGRATION_PR5382.md

@@ -0,0 +1 @@
+DOC: Add migration documentation for AnatomicalOrientation (PR #5382).

CMake/MigrationSentinels/ITK_MIGRATION_PR5721.md

@@ -0,0 +1 @@
+Modernize ITK Module System with CMake Interface Libraries (PR #5721).

CMake/MigrationSentinels/ITK_MIGRATION_PR5752.md

@@ -0,0 +1 @@
+COMP: Remove undefined long double swig wrapping (PR #5752).

CMake/MigrationSentinels/ITK_MIGRATION_PR5775.md

@@ -0,0 +1 @@
+BUG: Fix image_from_array shape handling for F-contiguous arrays (PR #5775).

CMake/MigrationSentinels/ITK_MIGRATION_PR5776.md

@@ -0,0 +1 @@
+ENH: Release Python GIL during ITK operations (PR #5776).

CMake/MigrationSentinels/ITK_MIGRATION_PR5791.md

@@ -0,0 +1 @@
+DOC: Add migration guide to updated GTest target names (PR #5791).

CMake/MigrationSentinels/ITK_MIGRATION_PR5803.md

@@ -0,0 +1 @@
+Deprecate `ImageConstIterator::GetIndex()`, use ComputeIndex() in tests and examples (PR #5803).

CMake/MigrationSentinels/ITK_MIGRATION_PR5995.md

@@ -0,0 +1 @@
+COMP: Use std::unique_ptr in FEMLinearSystemWrapperDenseVNL (PR #5995).

CMake/MigrationSentinels/ITK_MIGRATION_PR6003.md

@@ -0,0 +1 @@
+ENH: Use NumberToString for lossless float metadata in NIfTI reader (PR #6003).

CMake/MigrationSentinels/ITK_MIGRATION_PR6144.md

@@ -0,0 +1 @@
+COMP: Require VTK >= 9.1 in ITKVtkGlue; drop legacy module-system shims (PR #6144).

CMake/MigrationSentinels/ITK_MIGRATION_PR6183.md

@@ -0,0 +1 @@
+ENH: Replace custom LazyITKModule with native PEP 562 lazy loading (PR #6183).

CMake/MigrationSentinels/ITK_MIGRATION_PR6427.md

@@ -0,0 +1 @@
+ENH: Decouple itk::Math from vnl_math (constants and functions) (PR #6427).

CMake/MigrationSentinels/ITK_MIGRATION_PR6441.md

@@ -0,0 +1 @@
+ENH: PocketFFT as a permissive, dependency-free default FFT backend (PR #6441).

CMake/MigrationSentinels/ITK_MIGRATION_PR6469.md

@@ -0,0 +1 @@
+ENH: Reimplement GDCMSeriesFileNames on gdcm::IPPSorter/Scanner (drop deprecated SerieHelper) (PR #6469).

CMake/MigrationSentinels/ITK_MIGRATION_PR6475.md

@@ -0,0 +1 @@
+ENH: Eigen-backed itk eigendecompositions; deprecate vnl_*_eigensystem and eispack (PR #6475).

CMake/MigrationSentinels/ITK_MIGRATION_PR6487.md

@@ -0,0 +1 @@
+ENH: Add Eigen-backed itk::Math::SVD and migrate ITK's vnl_svd consumers (PR #6487).

CMake/MigrationSentinels/ITK_MIGRATION_PR6504.md

@@ -0,0 +1 @@
+COMP: Modernize deprecated macros in ingested filter/IO modules (PR #6504).

CMake/MigrationSentinels/ITK_MIGRATION_PR6524.md

@@ -0,0 +1 @@
+ENH: Retire FEM modules to InsightSoftwareConsortium/ITKFEM remote (PR #6524).

CMake/MigrationSentinels/ITK_MIGRATION_PR6553.md

@@ -0,0 +1 @@
+DOC: Document itkDCMTKFileReader privatization in ITKv6 migration guide (PR #6553).

CMake/MigrationSentinels/ITK_MIGRATION_PR6569.md

@@ -0,0 +1 @@
+BUG: Fix JointHistogramMutualInformation metric marginals and derivative (PR #6569).

CMake/MigrationSentinels/ITK_MIGRATION_PR6573.md

@@ -0,0 +1 @@
+Deprecate mpl::IsNumber (PR #6573).

CMake/MigrationSentinels/ITK_MIGRATION_PR6594.md

@@ -0,0 +1 @@
+BUG: Center collapsed-axis origin in projection and accumulate filters (PR #6594).

CMake/MigrationSentinels/ITK_MIGRATION_PR6602.md

@@ -0,0 +1 @@
+BUG: Smooth structure tensor with an isotropic Gaussian kernel (PR #6602).

CMake/MigrationSentinels/ITK_MIGRATION_PR6635.md

@@ -0,0 +1 @@
+BUG: Seed entropy threshold calculators with NonpositiveMin (PR #6635).

CMake/MigrationSentinels/ITK_MIGRATION_PR6649.md

@@ -0,0 +1 @@
+DOC: note HDF5ImageIO compression-default change in migration guide (PR #6649).

CMake/MigrationSentinels/README.md

@@ -0,0 +1,12 @@
+# Migration sentinels
+
+Each `ITK_MIGRATION_*.md` file in this directory asserts that one
+downstream-visible change is present in this ITK source tree. The filenames are
+collected into `ITK_MIGRATION_SENTINELS` at configure time and exported through
+`ITKConfig.cmake`, so downstream projects can gate on a specific change during
+the interval between ITK tags.
+
+Add one file per downstream-visible change. See
+`Documentation/docs/contributing/migration_sentinels.md`.
+
+This file is not a sentinel: the glob matches only `ITK_MIGRATION_*.md`.

CMake/itkMigrationSentinels.cmake

@@ -0,0 +1,28 @@
+# Migration sentinels: one Markdown file per downstream-visible change.
+#
+# The resulting list is exported through ITKConfig.cmake ONLY. It must never
+# reach itkConfigure.h or any other compiled header: the value changes on most
+# merges, and that header is included nearly everywhere, so embedding it would
+# invalidate ccache for every translation unit on every build machine.
+function(itk_collect_migration_sentinels _sentinel_dir _out_var)
+  # CONFIGURE_DEPENDS is required during a real configure: without it, adding
+  # a sentinel file does not re-run CMake and the new sentinel is silently
+  # missed. It is rejected in -P script mode (CMAKE_SCRIPT_MODE_FILE set),
+  # which the CollectTest.cmake unit test runs under.
+  if(CMAKE_SCRIPT_MODE_FILE)
+    file(GLOB _sentinel_files "${_sentinel_dir}/ITK_MIGRATION_*.md")
+  else()
+    file(
+      GLOB _sentinel_files
+      CONFIGURE_DEPENDS
+      "${_sentinel_dir}/ITK_MIGRATION_*.md"
+    )
+  endif()
+  set(_names "")
+  foreach(_file IN LISTS _sentinel_files)
+    get_filename_component(_name "${_file}" NAME_WE)
+    list(APPEND _names "${_name}")
+  endforeach()
+  list(SORT _names)
+  set(${_out_var} "${_names}" PARENT_SCOPE)
+endfunction()

CMakeLists.txt

@@ -56,6 +56,15 @@ set(
   ITK_VERSION
   "${ITK_VERSION_MAJOR}.${ITK_VERSION_MINOR}.${ITK_VERSION_PATCH}"
 )
+
+# Migration sentinels: exported through ITKConfig.cmake only, never into a
+# compiled header (see CMake/itkMigrationSentinels.cmake).
+include(itkMigrationSentinels)
+itk_collect_migration_sentinels(
+  "${CMAKE_CURRENT_SOURCE_DIR}/CMake/MigrationSentinels"
+  ITK_MIGRATION_SENTINELS
+)
+
 project(
   ITK
   VERSION ${ITK_VERSION}
@@ -903,6 +912,7 @@ if(BUILD_TESTING)
   )
   mark_as_advanced(CTEST_COST_DATA_FILE)
   add_subdirectory(Utilities/InstallTest)
+  add_subdirectory(Utilities/MigrationSentinelTest)
 endif()
 
 #-----------------------------------------------------------------------------

Documentation/docs/contributing/index.md

@@ -468,6 +468,7 @@ ITK Git Cheatsheet <https://github.com/InsightSoftwareConsortium/ITK/blob/main/D
 CDash Dashboard <https://open.cdash.org/index.php?project=Insight>
 dashboard.md
 updating_third_party.md
+migration_sentinels.md
 python_packaging.md
 ../README.md
 ```

Documentation/docs/contributing/migration_sentinels.md

@@ -0,0 +1,85 @@
+# Migration sentinels
+
+A migration sentinel lets a downstream project detect, at CMake configure time,
+that one specific ITK change is present — during the interval between ITK tags,
+which can run two years.
+
+The motivating case is `git bisect`. A downstream project bisecting ITK to find
+which change broke it is configured against a sequence of arbitrary commits, and
+at each step must choose which baseline images to test against. Sentinels are
+plain files in the source tree, so they are readable in a detached `HEAD`, a
+shallow clone, or an exported archive — states in which `git describe` fails and
+`git rev-list --count` silently returns a wrong answer.
+
+Sentinels are **not** a general feature-detection API. They are removed at each
+tag. Sentinels are intended **only** for fine-grained configure-time decisions
+between tagged releases.
+
+## Adding a sentinel
+
+Add one file to `CMake/MigrationSentinels/` containing a single line of
+description:
+
+```
+CMake/MigrationSentinels/ITK_MIGRATION_PR6532.md
+```
+
+```markdown
+itk::Math::SVD replaces vnl_svd for ITK-internal consumers; see PR #6532.
+```
+
+Choose exactly one naming pattern:
+
+| Pattern | When |
+|---|---|
+| `ITK_MIGRATION_PR<N>` | **Strongly preferred** — traceable to the pull request. |
+| `ITK_MIGRATION_<DESCRIPTIVE_NAME>` | No single PR captures the change. |
+| `ITK_MIGRATION_HASH_<githash>` | Only a commit identifies the change. |
+
+CI rejects a name matching none of these. It also rejects a misspelled prefix,
+which would otherwise be silently ignored by the glob and never published.
+
+## Using a sentinel downstream
+
+```cmake
+find_package(ITK REQUIRED)
+
+if(ITK_VERSION VERSION_GREATER_EQUAL 6.1.0
+   OR ITK_MIGRATION_PR6532 IN_LIST ITK_MIGRATION_SENTINELS)
+  set(BASELINE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/Baseline/post-6532)
+else()
+  set(BASELINE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/Baseline/legacy)
+endif()
+```
+
+Name the ITK release you expect to contain the change as the version arm. Both
+arms are required:
+
+- The **sentinel arm** is true between tags, before any release contains it.
+- The **version arm** is true after the tag, once sentinels have been expired.
+
+Against an ITK predating this mechanism, `ITK_MIGRATION_SENTINELS` is unset,
+`IN_LIST` is false, and the legacy branch is taken — no guard needed. This is
+also why the mechanism is a list variable rather than a function: calling a
+function that older ITK does not define is a hard `Unknown CMake command`
+error, and CMake's `if()` cannot invoke a function anyway.
+
+## Expiring at a tag
+
+Run once after tagging:
+
+```bash
+python3 Utilities/Maintenance/MigrationSentinels.py expire-itk
+python3 Utilities/Maintenance/MigrationSentinels.py \
+  expire-downstream --tag 6.1.0 --repo ../BRAINSTools
+```
+
+Order does not matter and neither step is urgent. A downstream not yet rewritten
+keeps working against the tagged ITK because the version arm is now true.
+
+## Why this is not in a compiled header
+
+`ITK_MIGRATION_SENTINELS` is exported through `ITKConfig.cmake` only. Embedding
+it in `itkConfigure.h` would change every translation unit's preprocessed output
+on most merges and destroy ccache hit rates on every build machine. The
+`MigrationSentinelConfigureHeaderGuard` test enforces this.