ITK Release 4/What Developers Must Do To Contribute to the Users Migration Guide

< Users Migration Guide

What Information Must Be Captured

• Git hash of the ITKv4 commit that changed the API
• Migration guide page describing the justification for the change
  • Along the lines of:
  • Migration Users Guide
• Git hash of the Sequestered Applications commit that fixed the app to build with the new API

Proposed Procedures

General Ideas

• Gerrit review checklist
  • Step that asks "Does this patch change the API"
  • If so, have the changes been documented in the migration guide
  • Only accept if documented

• Documentation should include:
  • Names of files that change API
  • English explanation of changes
  • Code example of conversion from old API to new API

• Some parts of documentation could be auto-generated
  • Extract English explanation from git commit
  • Find conversion examples in diff of tests
  • Names of files generated from git commits as well

• Some sort of interface where automatic guesses for each migration component are auto-generated and developer can make changes to auto-generated results.
  • Maybe an addition to gerrit (how much gerrit editing can we do?)
  • If not, some sort of html form that is auto-populated from git and can be changed manually

Specific Proposals

• Git commit messages
  • If changes api, commit message must start with API - ...
  • API changes must include sections:
    • RATIONAL: english explanation of what the change is and why it was made
    • Possibly include OLD and NEW sections for sample code

• Gerrit post-review
  • Once change is fully reviewed and ready to be committed to master, developer must make a post to phpBB with full commit details
  • Forum post could be automatically populated by pulling in commit messages and/or review discussion from gerrit
  • Would then need to be manually edited by developer before final merge to master allowed

Workflow

File:MigrationGuideWorkFlow.pdf

Developer's Migration Guide Workflow

Implementation

• Any API Change commit must include a single XML file in a new Migration subdirectory
  • XML file requirements:
    • List of files effected
    • English description of change
    • Sample code of example fix
    • Any automated fix rules that can be included
  • XML file format:
    • Migration Guide XML Format
    • Sample Migration Guide XML files
  • This file can be generated by running the script:
    • ITK/Migration/InitializeXMLGuide.py