ITK Release 4/MigrationGuideDeveloperTutorial

General Steps

This tutorial provides a walkthrough of how to document changes made to the API during the ITKv4 development process. The steps of this guide only need to be followed when making an API change. The process consists of creating an XML document in the $ITK_SOURCE_DIR/Migration folder that represents the changes made to the API and including this document in the patch that gets reviewed in Gerrit.

Quick Version

1 - Make your change

(master)$ git checkout -b MyBranch
(MyBranch)$ vim Code/Common/itkInterestingFile.h
(MyBranch)$ ...
(MyBranch)$ git commit -a

2 - Initialize XML file

• note that this script is not yet in master
• current version is here

(MyBranch)$ python Migration/InitializeXMLGuide.py
Please enter a unique name for the XML document
>> MyDescriptiveName.xml

3 - Manually edit XML file

(MyBranch)$ vim Migration/MyDescriptiveName.xml

4 - Commit the XML file

(MyBranch)$ git add Migration/MyDescriptiveName.xml
(MyBranch)$ git commit

5 - Push to gerrit

(MyBranch)$ git push gerrit HEAD:refs/for/master/MyBranch

Detailed Version

Step 1 - Make the Change

• Start a new topic branch for the desired change

$ git checkout master
(master)$ git pull
(master)$ git checkout -b DescriptiveName
(DescriptiveName)$

• • This topic branch should only be used to make the desired API change (it should not combine multiple change topics)
  • Give the branch a descriptive name that corresponds to the nature of the API change
  • The topic branch name should correspond to the name for the XML document
• Make the API changes locally

(DescriptiveName)$ vim itkInterestingFile.h
(DescriptiveName *)$

• Commit the changes

(DescriptiveName *)$ git add itkInterestingFile.h
(DescriptiveName +)$ git commit
... This change takes itkInterestingFile and does such and such to it.  The change was made for the following really really good reason...
(DescriptiveName)$

• • The changes must be committed prior to using the automatic XML initialization tool
  • Make sure to use descriptive commit messages for all commits since they will be used by the automatic tool when initializing the XML document

Step 2 - Create the XML Document

• Follow the steps in either the Manual Instructions or the Automatic Instructions to create an XML document for the API change.
• XML documents from all API changes will live in $ITK_SOURCE_DIR/Migration
• Once written, commit the XML document to the local topic branch

(DescriptiveName *)$ git add Migration/DescriptiveName.xml
(DescriptiveName +)$ git commit
... DOC: Migration guide page
...
... Documenting such and such API change for the migration guide ...
(DescriptiveName)$

Step 3 - Review in Gerrit

• Once the XML document has been committed, push the topic branch to Gerrit for review
  • For more details on the pushing a topic to Gerrit, see the Gerrit Primer
• Make any changes desired by the members of the review committee

Step 4 - Finalize the Change

• Once the patch, including the Migration Guide XML document, has been accepted by the reivew committee, the topic is ready to be merged into master
• For instructions on merging to master, see the bottom of the Gerrit Primer