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

Tue May 31 11:21:01 EDT 2011

I'd like to second the comments by Luis.  The XML migration guide is a
very low bar for introducing API changes, and I've found them to be very
helpful in transitioning to ITKv4.

Hans

--
Hans J. Johnson, Ph.D.
hans-johnson at uiowa.edu
Assistant Professor of Psychiatry
University of Iowa Carver College of Medicine
W278 GH, 200 Hawkins Drive

Iowa City, Iowa 52242
Phone:  319-353-8587

-----Original Message-----
From: Luis Ibanez <luis.ibanez at kitware.com>
Date: Tue, 31 May 2011 11:18:26 -0400
To: Jim Miller <millerjv at ge.com>, Charles Marion
<charles.marion at kitware.com>
Cc: ITK <insight-developers at itk.org>
Subject: Re: [Insight-developers] How to prepare ITKv4 XML Migration Guide
pages

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
>
_______________________________________________
Powered by www.kitware.com

Visit other Kitware open-source projects at
http://www.kitware.com/opensource/opensource.html

Kitware offers ITK Training Courses, for more information visit:
http://kitware.com/products/protraining.html

Please keep messages on-topic and check the ITK FAQ at:
http://www.itk.org/Wiki/ITK_FAQ

Follow this link to subscribe/unsubscribe:
http://www.itk.org/mailman/listinfo/insight-developers

________________________________
Notice: This UI Health Care e-mail (including attachments) is covered by the Electronic Communications Privacy Act, 18 U.S.C. 2510-2521, is confidential and may be legally privileged.  If you are not the intended recipient, you are hereby notified that any retention, dissemination, distribution, or copying of this communication is strictly prohibited.  Please reply to the sender that you have received the message in error, then delete it.  Thank you.
________________________________