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

[Duncan Murdoch]

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