[Insight-developers] How to prepare ITKv4 XML Migration Guide pages

[Luis Ibanez]

Hi Jim,

I guess it is up for discussion among developers...
so we find the process that is efficient for everybody.

I would vote for including the XML files as part of Gerrit patches
(when they have ITK API changes), just to make sure that the
presence of the XML file is part of the check list for approving
a patch (...again, only if API changes are involved...).

The submission of the XML file to the Web pages of the migration
guide, should only happen as part of the "gerrit-merge" process
though.  Currently, the XML file is being sent as part of the
"gerrit-push" but that is something that we should fix very soon.

--

Having to write the XML migration page is part of the exercise
of exposing ITK developers to the impact that their changes will
have in the user community, and to make sure that some thought
has been put on how to mitigate such impact.


The Rationale is:
If we are not willing to deal with the cost of explaining the
change, then maybe that change is not that important after all.    :-)


     Luis


-----------------------------------
On Tue, May 31, 2011 at 8:56 AM, Jim Miller <millerjv at ge.com> wrote:
> Thanks Luis,
> Is is worth doing the migration guide piece as part of the initial gerrit
> submission? (Instead of waiting for the patch to be approved?)
> Jim
> On May 29, 2011, at 9:43 AM, Luis Ibanez wrote:
>
> Hi Jim,
>
> Following up on the discussion during the tcon,
>
>
> Here is the method for generating entries for the
> ITKv4 Migration Guide:
>
>                  http://ij.itk.org/itkfaq/
>
>
> 1) Prepare Gerrit patches as usual.
>
> 2) Review them, get them approved.
>
> 3) Once approved, (and before merging them)
>
>     on the git branch that contains the patch,
>     run the python script:
>
>     .Documentation/Migration/InitializeXMLGuide.py
>
>    It will ask you for a unique name to be used
>    for the generated XML file.
>
>    Please be generous with the name length and
>    specificity because we probably will end up
>    with hundreds of these files.
>
>    For example,
>    a good name for your changes could be:
>
>    StatisticsFrameworkResolveDecisionRulesDuplicates.xml
>
>
> 4)  The python script will put the resulting XML file
>    in the directory:
>
>                ./Documentation/Migration/
>
>    at that point, you can edit it to document the details
>    of the change.
>
>    You may want to pay particular attention at the sections
>
>              A) Description
>              B) Sample Code
>
>    Section (B) is what future applications developers
>    would want to see as the instructions on how to modify
>    the ITK 3.x-based code, to use ITKv4.
>
>
> 5)  Once you are satisfied with the descriptions,
>
>    add this file to your branch,
>
>    (git add, git commit --amend)
>
>    and merge the approved branch
>    with the usual command
>
>                 git    gerrit-merge
>
>
>
> At that point, behind the scenes a Git hook
> will capture the XML file and will submit it to
> the ITK Migration Guide system online.
>
>                  http://ij.itk.org/itkfaq/
>
> If needed, you can do further edits to the
> online page as well.
>
>
> ---------------------
>
>
> More details about this process
> are available in the Wiki:
>
> http://itk.org/Wiki/ITK_Release_4/What_Developers_Must_Do_To_Contribute_to_the_Users_Migration_Guide
>
>
> http://itk.org/Wiki/ITK_Release_4/Users_Migration_Guide
> http://itk.org/Wiki/ITK_Release_4/MigrationGuideDeveloperTutorial
>
>
>    Luis
>
> Jim Miller
> Senior Scientist
> GE Research
> Interventional and Therapy
> GE imagination at work
>