[hjmjohnson]

WIP: FOR REVIEW. This is a full working implementation of #7131, so the design can be judged by its real output. Each change adds one small YAML migration record, and the docs build generates the migration guides from them. No PR edits a shared guide file again.

The generated guides are in this PR's Read the Docs preview, and as raw snapshots for review on GitHub: itk_6_migration_guide_DRAFT.md and itk_5_migration_guide_DRAFT.md. Criticism of the records' content, and of the layout and ranking, is the point of this draft.

Commits

1. DOC: Document migration records.
   • Documentation/AI/migration-records.md is the one guide, for contributors and agents. It covers when a change needs a record and how to write one.
   • The JSON Schema is the single definition of each field and of the impact rubric. _template.yaml is generated from it.
   • The template's core fields are live with generic example values, and optional fields are commented. Uncomment an optional field once it has a value; removing unused fields before committing is recommended, not required.
   • Also adds a row in AGENTS.md, a checklist line in pull-requests.md, and a link from the contributing docs.
2. ENH: Generate the migration guides from records.
   • Utilities/Maintenance/MigrationRecords.py has four subcommands: validate, generate, template, and release. It is also the Sphinx extension that builds the guide pages.
   • New pre-commit hooks: advisory validation, and local generation into the git-ignored migration_guides/generated/.
   • SetupForDevelopment.sh generates the pages once, and its version is bumped to 13 so existing clones rerun it. The release checklist gains a step that assigns records to the new release.
   • Fixture tests run in the pre-commit workflow.
3. DOC: Freeze the hand-written guides. Their old URLs redirect to the generated pages. They keep their content, gain a "frozen" note, and leave the docs build. Open PRs that append to them still rebase cleanly (11 of 33 open PRs touch migration_guides/). A later cleanup PR converts late additions and deletes the files.
4. DOC: Convert the existing entries into records.
   • Counts: 92 records, 51 in itk6/ and 41 in itk5/. Catch-all sections are split into one record per change, and each split record starts with its section's heading in bold.
   • Wording: the words are the originals, moved into fields without rewriting, typos included. An audit of every paragraph, list item, table row, and code line, in both directions, finds nothing lost or added.
   • Releases: the releases.yaml manifests come from git tag --contains on each record's commit. 42 ITK 6 records are in no tag yet and show as Unreleased.
5. WIP: Snapshots of the generated guides (*_DRAFT.md), for review on GitHub only. They are excluded from the docs build and not kept up to date. Drop this commit before merge.

Record format

The file is records/itk<N>/YYYYMMDD_<Descriptor>.yaml, and the descriptor is the record's ID and anchor. Every field is optional, so {} is valid. The fields are:

• title, summary, details, actions;
• categories (what changed) and environment (where to act);
• impact: high, medium, or low, rated with the rubric in the schema;
• pr, and commits: the commit that introduced the change first, then follow-up fixes appended over time;
• deprecated_in, removed_in, legacy_guard;
• renames and before/after examples.
• hints: freeform pointers for people and agentic tools doing the migration, such as scripts in Utilities/Maintenance/ or sed/grep commands. They are not shown in the guide.

Markdown fields are limited to the subset that renders the same on GitHub and in MyST. Releases live in releases.yaml, written only by MigrationRecords.py release, and unlisted records appear under "Unreleased".

Validation is advisory

The hook prints suggestions and never blocks. ITK_MIGRATION_RECORDS_STRICT=1 makes errors fail, for anyone who opts in. Schema checks use the jsonschema library (the engine behind check-jsonschema) and style checks use yamllint, both inside one local hook. That keeps both advisory; a standalone check-jsonschema or yamllint hook would block commits.

Open questions for review

• A full docs build gives 29 warnings, down from 74 on main, because the old guide's heading warnings are gone. The generated pages add only two inherited CMake highlighting warnings, from ... placeholders in example code.
• The impact ratings of the converted records are first guesses from the rubric; please correct them.
• The "Fine-grained versioning between release tags" section stays in migration_guides/index.md because it describes a mechanism, not a migration.

🤖 Generated with Claude Code

[hjmjohnson]

Force-push 0571025→0e3c9a0 is content-only (same base): bumps SetupForDevelopment_VERSION to 13, replaces commit with a commits list (introducing commit first, follow-up fixes appended), and adds a WIP: commit with *_DRAFT.md snapshots of the generated guides for review, to be dropped before merge.

[hjmjohnson]

Force-push 0e3c9a0→752d930 is content-only (same base): following @dzenanz on #7131, each generated guide now opens with Most impactful changes (every high-impact record, with what to do) followed by All changes (the index and every record by release). The *_DRAFT.md snapshots are regenerated to match.

[hjmjohnson]

Force-push 752d930→ad304e9 is content-only (same base): adds an optional hints field, a freeform list of pointers for people and agentic tools carrying out a migration (scripts in Utilities/Maintenance/, sed/grep commands). Hints are not rendered in the guide. Four ITK 6 records carry examples.

[hjmjohnson]

Force-push ad304e9→4ff2902 is content-only (same base).

• Records are now verbatim. Every record's prose is the original guide text, moved into fields without rewriting, typos included. A record split from a catch-all section ("Class changes", "C++11", …) starts with that section's heading in bold.
• Verified by an audit. It checks every paragraph, list item, table row, and code line of the frozen guides in both directions. Only the guides' own titles and intros are unplaced, plus one HTML anchor tag whose paragraph is in the record. No record holds prose that is not in the originals.
• Documentation/AI/migration-records.md now separates the two tiers of rule-tiers.md:
  • Project standards decide whether a record is acceptable, and have no length limit.
  • Agent default: generation guidelines hold the brevity limits. They constrain how an agent writes a record and are not acceptance criteria, so reviewers (Greptile included) should not cite them.

[dzenanz]

Mostly looks good.

[hjmjohnson]

Force-push 4ff2902→14dbe40 is content-only (same base): per @dzenanz, the template now has its core fields live with generic example values and optional fields commented, with header steps for uncommenting. The validator flags an unedited copy. Details are in the resolved template thread.

[hjmjohnson]

Force-push 14dbe40→18016e7 is content-only (same base): MathSqrtepsOneUlp keeps impact: low (the rubric uses it as the low example) and gains one details line giving the reason, which clears the advisory warning. That line is the one sentence in the converted records not taken from the original guide.

[hjmjohnson]

@greptile review

[hjmjohnson]

Force-push 18016e7→5d5405e is a rebase only, onto main (587858a). All five commits are unchanged (git range-diff: =). A content push follows with the Greptile fixes and records for the SSE2 (#7125) and Visual Studio 16.2 (#7129) sections added to the frozen guide.

[hjmjohnson]

Force-push 5d5405e→4d00fe1 is content-only (same base): Greptile fixes (wrong field types no longer crash, UTF-8 everywhere, redirects at the old guide URLs, multi-line actions), and records for the three sections added to the frozen guide by #7125, #7129, and #7123, converted verbatim. 91 records in all.

[hjmjohnson]

Force-push 4d00fe1→583f099 is a rebase only, onto main (4dbf738). All five commits are unchanged (git range-diff: =). A content push follows that adds the record for the work-unit ratio section #7122 added to the frozen guide.

[hjmjohnson]

Force-push 583f099→d459af4 is content-only (same base): adds 20261106_WorkUnitPerThreadRatio.yaml, the verbatim record for the work-unit ratio section #7122 added to the frozen guide. 92 records in all.

[hjmjohnson]

Force-push d459af4→dc6c7e9 changes commit messages only (tree identical, same base): removes the Co-Authored-By: Claude … trailers, which Documentation/AI/attribution.md forbids. AI assistance is disclosed in the PR description only.