[Insight-developers] Migration guides docs editing

[David Cole]

On Tue, Aug 16, 2011 at 11:55 AM, Cory Quammen <cquammen at cs.unc.edu> wrote:
> 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
>

It's definitely the right thing to do. Make it easy for the users of
the migration guide, including referencing multiple gerrit change IDs.
If we have to, we should adapt our processing of the xml documents to
account for this fact.


David C.

> 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
>