RE: [dsdp-tm-dev] 2.0 API Changes vs. Migration Document

["Oberhuber, Martin" <Martin.Oberhuber@xxxxxxxxxxxxx>]

Great idea, though I do not think assembling it with a script
will make sense -- since multiple API changes may easily make
each other obsolete.

Other suggestions?

Cheers,
--
Martin Oberhuber
Wind River Systems, Inc.
Target Management Project Lead, DSDP PMC Member
http://www.eclipse.org/dsdp/tm 

> -----Original Message-----
> From: dsdp-tm-dev-bounces@xxxxxxxxxxx 
> [mailto:dsdp-tm-dev-bounces@xxxxxxxxxxx] On Behalf Of David Dykstal
> Sent: Thursday, December 21, 2006 7:28 PM
> To: Target Management developer discussions
> Subject: Re: [dsdp-tm-dev] 2.0 API Changes vs. Migration Document
> 
> All changes should be done with a bug report tagged with 
> [api]. Maybe  
> we can keep the documentation in a tagged comment of the bug report?  
> Is it possible to construct a query looking for the last occurrence  
> of a comment tagged as [migration]? We could eventually copy 
> this out  
> of the bug report into a migration guide in the ISV doc.
> 
> The advantages to this are that
> (1) it limits the amount of places developers must visit and so it's  
> more likely to get done
> (2) it could be checked and perhaps assembled by a script
> ---------------------------
> Dave Dykstal
> dykstal@xxxxxxx
> 
> 
> On Dec 21, 2006, at 12:01 PM, Oberhuber, Martin wrote:
> 
> > Hi all,
> >
> > as we'll be going to implemented RSE API Changes
> > in the 2.0 stream, we should start thinking about
> > the format in which we want to record the list of
> > changes made and especially the steps that our
> > users need to take to migrate.
> >
> > I believe that such a migration document will be
> > much easier to create if it's started with the
> > first API change as it happens, and maintained
> > along the way.
> >
> > During the 1.0 stream, we've been using the build
> > notes to track this, but I believe that in the 2.0
> > stream we'll have more (and potentially more complex)
> > changes, so we should have a more versatile format
> > for tracking this.
> >
> > Proposals include:
> > (a) Track changes / migration info inside the ISV docs?
> > (b) -"- in the Wiki?
> > (c) -"- as a separate HTML document in the Repository?
> > (d) -"- as a separate HTML document on the Website?
> >
> > Advantage of the Wiki is that users can also edit it
> > and add their own information / experiences with migration.
> > Advantage of the CVS Repository is that it provides for
> > better change management.
> >
> > I'd envision the document to be in a standard format
> > that lists like the following items for each change:
> > - Description (what happened?)
> > - User Impact (what does it mean to user code?)
> > - Migration (what does the user need to do?)
> >
> > Any thoughts on this? Is it too process heavy and would
> > we be solving a problem that our users don't have since
> > there are not many developing against 1.0? Or is it just
> > right? What should be the granularity of tracked changes
> > -- one entry for every bugzilla item, or should we group
> > changes together in the end like all package renamings
> > in one place because migration is the same for all
> > ("Organize Imports")?
> >
> >
> > Cheers,
> > --
> > Martin Oberhuber
> > Wind River Systems, Inc.
> > Target Management Project Lead, DSDP PMC Member
> > http://www.eclipse.org/dsdp/tm
> > _______________________________________________
> > dsdp-tm-dev mailing list
> > dsdp-tm-dev@xxxxxxxxxxx
> > https://dev.eclipse.org/mailman/listinfo/dsdp-tm-dev
> 
> _______________________________________________
> dsdp-tm-dev mailing list
> dsdp-tm-dev@xxxxxxxxxxx
> https://dev.eclipse.org/mailman/listinfo/dsdp-tm-dev
>