[Bioc-devel] best way to transition users to new version of package

[Robert M. Flight]

Thanks Martin. I've already been working on the new version as a separate
package, although branched from the previous code base because I was
planning on merging it back in.

After some thought, I do think the best way to do it will be to deprecate
the original package, including the name of the new package in the
deprecated version.

I also agree it would be important to provide a vignette providing a guide
to the new functionality compared to the old.

-Robert

On Thu, May 28, 2015, 10:46 AM Martin Morgan <mtmorgan at fredhutch.org> wrote:

> On 05/28/2015 06:32 AM, Robert M. Flight wrote:
> > Thanks for the feedback Wolfgang. I never thought to look at how many
> > packages in Bioconductor have a baseName and baseName2 to see how often
> > this is done. I assume based on the existence of Roxygen2 and ggplot2
> that
> > there were initial versions of those named Roxygen and ggplot.
> >
> > This also seems like it is probably the easiest way forward for myself
> and
> > the users.
>
> I'm not sure that this is best, but I'd be aggressive about getting rid of
> an
> old package, with 'due course' being over a release --
>
>    -----|-----|-----|
>           ^    ^
>           ^    defunct v.1
>           intro v.2, deprecate v.1
>
> Your users will be more actively encouraged to get the benefit of your new
> design, rather than stumbling around in no-longer-supported code. It seems
> responsible to provide some kind of migration guide vignette; this might be
> quite easy -- a lot of your re-organization might well be business
> internal to
> the package, with the user-facing API relatively unchanging.
>
> Because the time frame for the transition is short, this might tip the
> balance
> from introducing a new package to incorporating your revisions in the
> original,
> getting the 'advertising' benefit of a single package name.
>
> The notes at
>
>    http://bioconductor.org/developers/how-to/deprecation/
>    http://bioconductor.org/developers/package-end-of-life/
>
> describe best practices for function and package deprecation (maybe the
> material
> will be re-organized a bit...).
>
> Martin
>
> >
> > Regards,
> >
> > -Robert
> >
> > On Wed, May 27, 2015 at 2:45 PM Wolfgang Huber <whuber at embl.de> wrote:
> >
> >> Robert
> >>
> >> with the packages cellHTS, cellHTS2 and DESeq, DESeq2 (and with the
> >> functions vsn, vsn2 in the vsn package) I three times chose route 1,
> and am
> >> generally happy about it. In due time, you can deprecate and then
> defunct
> >> the old one.
> >>
> >> Option 2 seems needlessly disruptive (potentially). A large fraction of
> >> users you never ‘see’ or get in contact with. Not sure how that
> translates
> >> into absolute numbers of course.
> >>
> >> With option 3 it seems difficult to implement the exact same (and
> probably
> >> unsatisfactory) behaviour that people are used to.
> >>
> >> People also seem used to that from other products (WIndows 3.1, or now
> >> soon 10; iphone 6; X11; HTML5; …)
> >>
> >> Best wishes
> >>          Wolfgang
> >>
> >>> On 27 May 2015, at 17:10, Robert M. Flight <rflight79 at gmail.com>
> wrote:
> >>>
> >>> I am the author and maintainer of the categoryCompare package on
> >>> Bioconductor. As I and others have used it over the years, I am seeing
> >> that
> >>> there are a lot of design mistakes in the code, and that it was not
> >>> extensible in it's current form. Therefore, I decided to do a complete
> >>> rewrite starting from scratch. Because of a new logic, I decided on a
> >>> completely new function naming scheme, class names, etc.
> >>>
> >>> There are currently no packages on Bioconductor that depend on my
> >> package,
> >>> and I only know of a handful of other users that are actively using it
> (I
> >>> have no posts on the support forum, and I've only gotten three emails
> >>> directly with questions about using it).
> >>>
> >>> I'm trying to figure out how best to transition the few users who may
> >> have
> >>> analysis code relying on the package. I have three possibilities in
> mind,
> >>> ranging from what I consider most radical to least, and probably least
> >>> amount of work on my part to most:
> >>>
> >>> 1 - change name of new package to categoryComare2 or something else.
> May
> >>> lose old users who don't find the package. Could be mitigated by adding
> >>> startupMessage to the next iteration of the original package, and
> adding
> >>> information to Bioconductor landing page
> >>>
> >>> 2 - add startupMessage's pointing users to vignettes with new workflow
> >> and
> >>> functions, warning that old functions are completely gone.
> >>>
> >>> 3 - provide wrappers with the same names as old package functions that
> >> use
> >>> new functions under the hood, with warning that they will be deprecated
> >> in
> >>> next version.
> >>>
> >>> I'd appreciate feedback on what the best approach would be in this
> case.
> >>>
> >>> Cheers,
> >>>
> >>> -Robert
> >>>
> >>> Robert M Flight, PhD
> >>> Bioinformatics Research Associate
> >>> Resource Center for Stable Isotope Resolved Metabolomics
> >>> Markey Cancer Center
> >>> University of Kentucky
> >>> Lexington, KY
> >>>
> >>> Twitter: @rmflight
> >>> Web: rmflight.github.io
> >>> EM rflight79 at gmail.com
> >>> PH 502-509-1827
> >>>
> >>> The most exciting phrase to hear in science, the one that heralds new
> >>> discoveries, is not "Eureka!" (I found it!) but "That's funny ..." -
> >> Isaac
> >>> Asimov
> >>>
> >>>        [[alternative HTML version deleted]]
> >>>
> >>> _______________________________________________
> >>> Bioc-devel at r-project.org mailing list
> >>> https://stat.ethz.ch/mailman/listinfo/bioc-devel
> >>
> >>
> >
> >       [[alternative HTML version deleted]]
> >
> > _______________________________________________
> > Bioc-devel at r-project.org mailing list
> > https://stat.ethz.ch/mailman/listinfo/bioc-devel
> >
>
>
> --
> Computational Biology / Fred Hutchinson Cancer Research Center
> 1100 Fairview Ave. N.
> PO Box 19024 Seattle, WA 98109
>
> Location: Arnold Building M1 B861
> Phone: (206) 667-2793
>

	[[alternative HTML version deleted]]