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

From KitwarePublic
Jump to navigationJump to search
No edit summary
Line 52: Line 52:
[[File:MigrationGuideWorkFlow.pdf|PDF File]]
[[File:MigrationGuideWorkFlow.pdf|PDF File]]


 
[[ITK_Release_4/Users_Migration_Guide/Developer_Migration_Guide_Workflow|Developer's Migration Guide Workflow]]
{| border="1"
|-
| [[File:MigrationGuideWorkFlow1.png]]
| '''Initial Setup'''
* Published migration guide pulled directly from ''master'' XML files
* Sequestered applications compiling correctly
|-
| [[File:MigrationGuideWorkFlow2.png]]
| '''Topic Branch'''
* Standard git workflow
|-
| [[File:MigrationGuideWorkFlow3.png]]
| '''Local Changes'''
* Standard git workflow
|-
| [[File:MigrationGuideWorkFlow4.png]]
| '''Migration Guide XML'''
* Before pushing topic to Gerrit, must create a unique XML document that documents changes to API
* XML documents will live in the source tree in a new directory
|-
| [[File:MigrationGuideWorkFlow5.png]]
| '''Gerrit Review'''
* Standard Gerrit review process
* Make any necessary changes
|-
| [[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]]
| '''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]]
| '''Applications Fail'''
|-
| [[File:MigrationGuideWorkFlow9.png]]
| '''Create Applications Topic Branch'''
* Checkout current version of sequestered applications
|-
| [[File:MigrationGuideWorkFlow10.png]]
| '''Fix Broken Applications'''
* Make necessary changes to fix compilation errors for the applications
|-
| [[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]]
| '''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 15:24, 14 October 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

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=32426"