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
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
- 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:
- This file can be generated by running the script:
- ITK/Migration/InitializeXMLGuide.py
- XML file requirements: