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.

The files should be placed in $ITK_SOURCE_DIR/Migration.

Example Files

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

• <MigrationGuideTag>: A tag for categorizing the change on the Migration Guide.
• <MigrationFix-Automatic>: A rule for the 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>: 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. 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.