ITK Release 4/What Developers Must Do To Contribute to the Users Migration Guide: Difference between revisions
From KitwarePublic
Jump to navigationJump to search
Line 71: | Line 71: | ||
|- | |- | ||
| [[File:MigrationGuideWorkFlow5.png]] | | [[File:MigrationGuideWorkFlow5.png]] | ||
| | | '''Gerrit Review''' | ||
* Standard Gerrit review process | |||
* Make any necessary changes | |||
|- | |- | ||
| [[File:MigrationGuideWorkFlow6.png]] | | [[File:MigrationGuideWorkFlow6.png]] | ||
| | | '''Finalize Migration Guide XML''' | ||
* Before review can be completed, the XML file must be revised to accurately reflect API changes | |||
|- | |- | ||
| [[File:MigrationGuideWorkFlow7.png]] | | [[File:MigrationGuideWorkFlow7.png]] | ||
| | | '''Merge to master''' | ||
* Merge the topic branch to ''master'' in the normal manner using ''stage'' | |||
* Once change is merged into ''master'', the published migration guide will automatically update | |||
* Wait for nightly Sequestered Applications builds | |||
|- | |- | ||
| [[File:MigrationGuideWorkFlow8.png]] | | [[File:MigrationGuideWorkFlow8.png]] | ||
| | | '''Applications Fail''' | ||
|- | |- | ||
| [[File:MigrationGuideWorkFlow9.png]] | | [[File:MigrationGuideWorkFlow9.png]] | ||
| | | '''Create Applications Topic Branch''' | ||
* Checkout current version of sequestered applications | |||
|- | |- | ||
| [[File:MigrationGuideWorkFlow10.png]] | | [[File:MigrationGuideWorkFlow10.png]] | ||
| | | '''Fix Broken Applications''' | ||
* Make necessary changes to fix compilation errors for the applications | |||
|- | |- | ||
| [[File:MigrationGuideWorkFlow11.png]] | | [[File:MigrationGuideWorkFlow11.png]] | ||
| | | '''Add Migration Guide Links''' | ||
* Add a list to the XML file that shows each unique compilation error and links to the fix | |||
* Need more details on where fixes will live (phpBB, Git repo, ...?) | |||
|- | |- | ||
| [[File:MigrationGuideWorkFlow12.png]] | | [[File:MigrationGuideWorkFlow12.png]] | ||
| | | '''Merge Directly to master''' | ||
* Once all applications are fixed, merge the updated XML file directly to ''master'' | |||
* Do not need to go through Gerrit review process | |||
|} | |} |
Revision as of 21:15, 13 October 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