[R-pkg-devel] Notifying users of major changes

[William Becker]

Dear All,

Thanks for all the advice on this. My plan is now to generate messages from old functions that point to the new function equivalent. The .Deprecated/.Defunct functions look very helpful in this regard. I will also write a vignette explaining all the changes as suggested, to try to ease the transition. I already put up an advance notice on the readme on GitHub which may also help a bit.

Thanks again for the help,
Will

> On 02/03/2022 10:14 Lluís Revilla <lluis.revilla using gmail.com> wrote:
> 
>  
> Dear all,
> 
> Doesn't R have a couple of functions for that?
> On base there is a function to notify users of a close removal with
> .Deprecated.
> When the function is finally removed the .Defunct function can be used
> to notify the users too.
> Other packages use their own functions to notify users or those functions
> on the lifecycle package.
> 
> Cheers,
> 
> Lluís
> 
> 
> 
> On Wed, 2 Mar 2022 at 08:38, Vincent van Hees <vincentvanhees using gmail.com>
> wrote:
> 
> > Dear Will,
> > I agree with the suggestions from Duncan. Additionally, you could consider
> > facilitating both new and old syntax for a certain transition period e.g. 1
> > year. During this transition period you would show a warning message to
> > users of the old syntax.
> > When the transition period is over you replace the warning by an error and
> > start deprecating code relating to the old syntax. This will make the
> > transition less abrupt for users. However, it comes with the cost of having
> > to maintain both syntaxes. I tend use this when I deprecate or change the
> > name of my function arguments.
> > Vincent
> >
> >
> >
> >
> >
> > On Mon, 28 Feb 2022 at 20:32, Duncan Murdoch <murdoch.duncan using gmail.com>
> > wrote:
> >
> > > On 28/02/2022 9:51 a.m., William Becker wrote:
> > > > Dear All,
> > > >
> > > > I'm new to this list so my apologies if a similar question has been
> > > asked recently.
> > > >
> > > > I'm the maintainer of a package released last year (COINr). I am
> > working
> > > on some major upgrades to the package which will unfortunately change a
> > lot
> > > of the syntax. I know this will disrupt the users but the upgrades are
> > > substantial improvements and the underlying code is a lot more stable and
> > > robust. Moreover the package is high level so there are no reverse
> > > dependencies, and I thought I might as well get this done as early as
> > > possible so as to minimise the number of people affected. Obviously this
> > is
> > > a one-off and in future the package will be backwards compatible.
> > > >
> > > > Anyway to the question: I would like to warn users up front about the
> > > upcoming disruptive changes. What's the best way to do this? I can put a
> > > notice on the package's GitHub page. Or would it make sense to release a
> > > minor update with a package startup message warning about the impending
> > > upgrade? Or is there another way?
> > > >
> > >
> > > I don't think there's a good way to connect with your users, other than
> > > printing a notice in the startup code and trying to recognize that they
> > > are using syntax that doesn't work in the new version.  I wouldn't
> > > bother with the minor update that just warns about upcoming changes,
> > > because at the point the user sees those, they won't be able to do
> > > anything about them.
> > >
> > > I would put warnings or errors about using obsolete syntax into the new
> > > version if you can recognize it.  Include a vignette that shows old and
> > > new ways to do some of the common operations, and tell users which is
> > > the last version that supports the old syntax in case they are desperate
> > > and need to switch back.
> > >
> > > If your changes mean that the old syntax works but does something
> > > different now, well, I'd advise against that.  You could really mess up
> > > users who are using your package to automatically produce reports.
> > >
> > > In the extreme, you could create a new package (e.g. COINr2), and have
> > > one last update of COINr that tells users they should switch because you
> > > are going to stop maintaining it.  But it is better all around if you
> > > make all your changes in the existing package.
> > >
> > > Duncan Murdoch
> > >
> > > ______________________________________________
> > > R-package-devel using r-project.org mailing list
> > > https://stat.ethz.ch/mailman/listinfo/r-package-devel
> > >
> >
> >         [[alternative HTML version deleted]]
> >
> > ______________________________________________
> > R-package-devel using r-project.org mailing list
> > https://stat.ethz.ch/mailman/listinfo/r-package-devel
> >
> 
> 	[[alternative HTML version deleted]]
> 
> ______________________________________________
> R-package-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel

William Becker PhD
www.bluefoxdata.eu (http://www.bluefoxdata.eu) | Researchgate (https://www.researchgate.net/profile/William_Becker4) | LinkedIn (https://www.linkedin.com/in/webecker/) | GitHub (https://github.com/bluefoxr)