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. Using the automated initialization script, this should take roughly 10-15 minutes for simple changes.

Quick Version

1 - Make the change

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

2 - Initialize XML file

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

3 - Manually edit XML file

(DescriptiveName)$ vim Documentation/Migration/DescriptiveName.xml

4 - Commit the XML file

(DescriptiveName)$ git add Documentation/Migration/DescriptiveName.xml
(DescriptiveName)$ git commit

5 - Push to gerrit

(DescriptiveName)$ git gerrit-push

Detailed Version

Step 1 - Make the Change

Start a new topic branch for the desired change

$ git checkout master
(master)$ git pullall
(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/Documentation/Migration
• Once written, commit the XML document to the local topic branch

(DescriptiveName *)$ git add Documentation/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

(DescriptiveName)$ git gerrit-push

• 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

Manual XML Document Generation

• Create a new file in $ITK_SOURCE/Documentation/Migration/ with a unique name
• The file must follow the format:

<?xml version="1.0" encoding="UTF-8"?>

<Change>

  ...
  ...

</Change>

• The following elements must be defined inside the <Change> element in order for the change to be considered fully documented:
  • <Title>: English title for migration guide page
  • <Author>: Your name as the author of the change
  • <Date>: The date the XML file was made
  • <Description>: English description of what changes were made along with rational for making them.
  • <SampleCode>: Code snippet either manually written or automatically harvested from the patch's changes that illustrates how to update the API from the old version to the new version. This element must contain two child elements, <Old> and <New>. As their names suggest, these two elements contain the snippets of old API code and new API code.
  • <FileList>: A list of all files that were changed in association with the API change. File names should be specified relative to the base source directory for ITK.
  • <Gerrit-ChangeId>: This element links the API change to the Gerrit entry used to review the change.

• Additionally, the following elements should be added whenever possible:
  • <MigrationFix-Automatic>: A rule for the user migration tool that can automatically fix errors in user code. These fixes will be simple find-and-replace changes, so anything that cannot be replaced throughout the entire project will be a manual fix. This element must contain <Old> and <New> child elements.
  • <MigrationFix-Manual confidence="high">: A rule for the user migration tool that can not be automatcally fixed, but can be automatically identified. These rules will cause the user migration tool to flag a section of the code for revision. Most changes will fall in this category. The migration tool will simply search for the enclosed string and report that a problem may exist on the identified line. As such, the tool will most likely report locations that are not, in fact, problematic.
    • The confidence attribute is used to indicate the developer's confidence in the warning for this manual fix.
    • confidence options are high, medium, and low

• Finally, a <MigrationGuideTag> element can be added to specify keyword tags for the migration page

Automatic XML Document Generation

• Run the XML initialization script

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

• This script will parse the git history of the topic branch and create Documentation/Migration/DescriptiveName.xml
• In DescriptiveName.xml, the following elements must be manually edited:

<Description>

• The initialized field will look like:

<Description>
  ---- 839cfecfe678bb94836d94e85ecad87a82e9406e ----
  FIX: Fixed the API problem XXX
  
  This is a nice full description of what was changed in this
  commit and why.
  
  ---- eba124efeb163af974b9bf3b921b5724b1ece5d6 ----
  FIX: Started fixing API problem XXX
  
  This is also a nice description.
</Description>

• The end goal should look something like

<Description>
  This is a nice concise description of what happened over the
  course of all the commits for this topic. It takes advantage
  of all the information from the commit messages from the branch.
</Description>

• The goal behind populating the <Description> element with information from the commit messages is to ensure that the information from good git commits doesn't need to be duplicated
• Much of the initial body of this element will need to be removed (especially the commit hashes) since this will be what a user sees on the migration page

<SampleCode>

• This element will be populated by all the changes that have been made in files from the Examples and Testing directories
• The initial contents will look like:

<SampleCode>
  <Old>
  ---- InterestingExampleFile.cxx ----
  #include "OldName.h"

  ---- InterestingTestingFile.cxx ----
  filter->OldMethodName();
  </Old>
  
  <New>
  ---- InterestingExampleFile.cxx ----
  #include "NewName.h"

  ---- InterestingTestingFile.cxx ----
  filter->NewMethodName();
  </New>

</SampleCode>

• The final version should look something like

<SampleCode>
  <Old>
  #include "OldName.h"
  ...
  typedef InterestingFilter FilterType;
  FilterType::Pointer filter = FilterType::New();
  filter->OldMethodName();
  </Old>
  
  <New>
  #include "NewName.h"
  ...
  typedef InterestingFilter FilterType;
  FilterType::Pointer filter = FilterType::New();
  filter->NewMethodName();
  </New>

</SampleCode>

• The initial contents of this file should show examples of how applications (Examples and Tests) must be fixed for the new API change
• The goal of this element is to provide a concise overview of how to make these fixes, so the initial contents must be manually edited into a single example fix