Revision as of 21:16, 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
	Gerrit Review Standard Gerrit review process Make any necessary changes
	Finalize Migration Guide XML Before review can be completed, the XML file must be revised to accurately reflect API changes
	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
	Applications Fail
	Create Applications Topic Branch Checkout current version of sequestered applications
	Fix Broken Applications Make necessary changes to fix compilation errors for the applications
	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, ...?)
	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