ITK Release 4/What Developers Must Do To Contribute to the Users Migration Guide: Difference between revisions

From KitwarePublic
Jump to navigationJump to search
 
(21 intermediate revisions by 2 users not shown)
Line 1: Line 1:
[[ITK_Release_4/Users_Migration_Guide|< Users Migration Guide]]
= Overview =
= Overview =


Line 6: Line 8:
* Git hash of the ITKv4 commit that changed the API
* Git hash of the ITKv4 commit that changed the API
* Migration guide page describing the justification for the change
* Migration guide page describing the justification for the change
** Along the lines of:
** [[Proposals:Refactoring Statistics Framework 2007 Migration Users Guide | Migration Users Guide ]]
* Git hash of the Sequestered Applications commit that fixed the app to build with the new API
* Git hash of the Sequestered Applications commit that fixed the app to build with the new API


= Proposed Procedures =
= 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|PDF File]]
[[ITK_Release_4/Users_Migration_Guide/Developer_Migration_Guide_Workflow|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:
*** [[ITK_Release_4/Users_Migration_Guide/Migration_Guide_XML_Format|Migration Guide XML Format]]
*** [[ITK_Release_4/Users_Migration_Guide/Migration_Guide_XML_Samples|Sample Migration Guide XML files]]
** This file can be generated by running the script:
*** ITK/Migration/InitializeXMLGuide.py

Latest revision as of 17:53, 26 November 2010

< 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