[Insight-developers] Migration guides docs editing

Tue Aug 16 12:15:59 EDT 2011

Cory,

It is my feeling that the migration guide only needs to document for
external users how to get from 3.20 to 4.0, and it should not be overly
complicated by intermediate changes made during the alpha/beta phases of
updating 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: Cory Quammen <cquammen at cs.unc.edu>
Date: Tue, 16 Aug 2011 11:55:26 -0400
To: Charles Marion <charles.marion at kitware.com>
Cc: Julien Jomier <julien.jomier at kitware.com>, ITK
<insight-developers at itk.org>, Luis Ibanez <luis.ibanez at kitware.com>
Subject: Re: [Insight-developers] Migration guides docs editing

Charles,

Thanks for the info. I understand that all changes to the migration
guide should be done in the XML files. Mine is more of a process
question pertaining to how we document compound API changes rather
than a technical how-do-I-do-it question.

The issue is that there is an existing migration guide document for
one API change to the FFT classes. Now I am making another API change
that effectively invalidates the original migration guide document. I
have two choices: do I simply add a migration guide document that is
based on the state of the code *after* the first API change? Or do I
fix the existing migration guide document and lose the gerrit-id and
list of changed files from my gerrit patch?

Going with the first solution means that a person migrating from ITK 3
to ITK 4 would have to follow a chain of migration guide documents to
arrive at the correct ITK 4 code for using the FFT classes (make the
changes from the first document to get to the state expected by the
second document, then make the changes from the second document to
arrive at  the ITK 4 API). This seems like a ridiculous thing to
expect users to do. On the other hand, going with the second solution
discards some information about the gerrit patch that made the
*second* API change. Is that a big deal? If I could add a second
gerrit ID to a migration guide document, editing the original document
and adding the second gerrit ID seems like the best solution. But I
don't know if it is possible to add a second gerrit ID.

In my opinion, the migration guide should be as simple to use as
possible for an end user, so I favor simply modifying the existing
migration guide document. I just wanted to check with the community
that that is the right thing to do.

Thanks,
Cory

On Tue, Aug 16, 2011 at 11:16 AM, Charles Marion
<charles.marion at kitware.com> wrote:
> Hi Cory,
>
> The gerrit change is not Merged so the best way to fix the migration
> information is to create a new patch to the gerrit change.
> Once the changes are pushed, it will apply the changes to the migration
>guide.
>
> To do that, checkout the gerrit change:
> git fetch http://review.source.kitware.com/p/ITK
> refs/changes/76/2476/1 && git checkout FETCH_HEAD -b RenameFFTFilters
> Modify the xml file, commit it and push the changes to gerrit.
>
> Feel free to contact me if you have any questions.
>
> Charles
>
> 2011/8/16 Cory Quammen <cquammen at cs.unc.edu>:
>> [snip]
>>> are you suggesting to make modifications directly in the
>>> online forum page of the migration guide ?
>>>
>>> or
>>>
>>> are you referring to modifications to be made in the XML
>>> file and to be pushed to git first ?
>>
>> The latter (modifying the XML files). For a concrete example, please
>> see this gerrit patch: http://review.source.kitware.com/#change,2476.
>>
>> In this patch, I opted to modify the existing XML migration guide's
>> code snippets (FFTUseImageAsTemplateParameter.xml) to reflect the name
>> change in my patch and added another for my patch
>> (FFTFilterRename.xml). The code snippets are essentially the same,
>> though, so my new migration guide document seems redundant.
>>
>> Thanks in advance for your recommendations.
>>
>> Cory
>>
>>>    Thanks
>>>
>>>
>>>         Luis
>>>
>>> On Mon, Aug 15, 2011 at 10:47 AM, Cory Quammen <cquammen at cs.unc.edu>
>>>wrote:
>>>> I need some guidance from the migration guide team.
>>>>
>>>> Say someone makes an API change and documents it with a migration
>>>> guide XML document, and that this migration guide includes a snippet
>>>> showing how to convert old code to the new API.
>>>>
>>>> Now say I want to make a subsequent API change that invalidates the
>>>> original migration guide document, but it's just a name change, so
>>>> editing the existing migration guide document would be easy enough
>>>> (and seems like the right thing to do). If that's the case, do I just
>>>> add myself as an author to the migration guide document? Can I add a
>>>> gerrit-id to the <Gerrit-ChangeId> element? Do I add a date to the
>>>> <Date> element? Do I update the list of modified files? Or should I
>>>> just update the code examples and leave the rest alone?
>>>>
>>>> Thanks,
>>>> Cory
>>>>
>>>> --
>>>> Cory Quammen
>>>> Research Associate
>>>> Department of Computer Science
>>>> The University of North Carolina at Chapel Hill
>>>> _______________________________________________
>>>> 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
>>>>
>>>
>>
>>
>>
>> --
>> Cory Quammen
>> Research Associate
>> Department of Computer Science
>> The University of North Carolina at Chapel Hill
>>
>

--
Cory Quammen
Research Associate
Department of Computer Science
The University of North Carolina at Chapel Hill
_______________________________________________
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.
________________________________