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

[Martin Morgan]

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