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

From KitwarePublic
Jump to navigationJump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

< Users Migration Guide

Overview

What Information Must Be Captured

  • Git hash of the ITKv4 commit that changed the API
  • Migration guide page describing the justification for the change
  • 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:
    • This file can be generated by running the script:
      • ITK/Migration/InitializeXMLGuide.py
Retrieved from "https://public.kitware.com/Wiki/index.php?title=ITK_Release_4/What_Developers_Must_Do_To_Contribute_to_the_Users_Migration_Guide&oldid=34888"