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

[Vincent van Hees]

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]]