Revision as of 21:05, 13 October 2010

Overview

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

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

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

	Initial Setup Published migration guide pulled directly from master XML files Sequestered applications compiling correctly
	Topic Branch Standard git workflow
	Local Changes Standard git workflow
	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
	Blank
	Blank
	Blank
	Blank
	Blank
	Blank
	Blank
	Blank

@@ Line 53: / Line 53: @@
 |-
 | [[File:MigrationGuideWorkFlow1.png]]
-|Blank
+| '''Initial Setup'''
+* Published migration guide pulled directly from ''master'' XML files
+* Sequestered applications compiling correctly
 |-
 | [[File:MigrationGuideWorkFlow2.png]]
-|Blank
+| '''Topic Branch'''
+* Standard git workflow
 |-
 | [[File:MigrationGuideWorkFlow3.png]]
-|Blank
+| '''Local Changes'''
+* Standard git workflow
 |-
 | [[File:MigrationGuideWorkFlow4.png]]
-|Blank
+| '''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]]