InsightSoftwareConsortium / InsightSoftwareConsortium/ITK
DOC: Audit git history for undocumented API changes; add a ModernizationGuide
- Dominant language
- C++
- Stars
- 1.7k
- Forks
- 748
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 64
Description
ITK has migration guides for v5 and v6 but no companion guide for
*non-breaking* modernization advice, and the v6 guide has never been
audited against the commit history for completeness.
Part 1 — audit Migration Guide completeness
Sweep the commit history since `v5.4.5` for API-affecting changes and
verify each has an entry in
`Documentation/docs/migration_guides/itk_6_migration_guide.md` telling
users exactly how to update their code.
Entries should distinguish "breaks against 5.4.5" from "breaks against
current `main`", since downstream projects track both.
Part 2 — new ModernizationGuide.md
A companion document, sibling to the migration guides, for changes that
do **not** break the API:
- cosmetic / style modernizations (`auto` usage, `::Filled()`,
initialization at declaration)
- preparation for anticipated future changes (deprecation shims,
`ITK_FUTURE_LEGACY_REMOVE`)
- performance improvements available by opting into newer APIs
- better algorithmic results available from newer filters/options
Distinction from the migration guides: migration guide = "you must change
this or you won't compile"; modernization guide = "you may change this and
here's why you'd want to".
Current state in the repo
```
Documentation/docs/migration_guides/itk_5_migration_guide.md
Documentation/docs/migration_guides/itk_6_migration_guide.md
```
No `ModernizationGuide.md` (or any `*odernization*` file) exists anywhere
under `Documentation/`.
Contributor guide
Research direction
Start with Documentation/docs/migration_guides/itk_5_migration_guide.md and itk_6_migration_guide.md, then audit the commit history since v5.4.5 for API-affecting changes. Record whether each change breaks against v5.4.5 or current main, and document exact update guidance in the v6 guide. Add a sibling ModernizationGuide.md covering the listed non-breaking improvements and verify the distinction between migration and modernization guidance.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100