ITK Release 4/Users Migration Guide/Migration Guide XML Format

The goal of the migration guide XML documents is to encode all information about changes to the ITK API between the v3.X releases and v4.0. Each migration document consists of a single <Change> element and a set of associated child elements. The <Change> element has a set of required child elements and a set of additional optional child elements which can be used to automatically identify locations in user code where the API change will mandate updates. In the case of simple changes, these rules can be used to automatically fix user code with the migration tool.

Example File: File:MoveGetSetLengthMeasurementVectorTraits.xml

Required Child Elements

• <Title>: English title for migration guide page
• <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.

Optional Child Elements

• <ApplicationFixLink>: A link to git changes made when fixing sequestered applications that broke due to the API change.
• <MigrationFix-Automatic>: A rule for the migration tool that can automatically fix errors in user code. The current list of automatic fix types is:
  • "FileRename": Find and replace the file name with the new one. Must include <Old> and <New> child elements.
  • "ClassRename": Find and replace the name of a class. Must include <Old> and <New> child elements.
  • "ClassMove": Include the new location of the class. Must include <Old> and <New> child elements. Will warn the user that the old include file may be able to be removed but will not automatically remove it.
  • "MethodRename": Find and replace the name of the method. Must include <Old> and <New> child elements.
  • "MethodMove": Find and replace the name of a method. Only works if the method's signature hasn't changed. Must include <Old> and <New> child elements.
  • "NamespaceChange": Find object from the old namespace and update its namespace. This may not fix instances where "using namespace" is used so the migration tool should warn the user wherever the object's signature is found without a namespace attached. Must include <Old> and <New> child elements.
• <MigrationFix-Manual>: A rule for the migration tool that can not be automatcally fixed, but can be automatically identified. These rules will cause the migration tool to flag a section of the code for revision. The current type list is:
  • "MethodRefactor": Flag the user anywhere the changed method is called. Should be used any time a method's signature changes. Must include an <Old> child element.
  • "GeneralRefactor": Flag the user anywhere that the text specified in the <Old> child element is found.