At the cost of some level of reproducibility, you could use a static vignette and be very clear about the package versions used in the comparisons: http://www.markvanderloo.eu/yaRb/2019/01/11/add-a-static-pdf-vignette-to-an-r-package/
As this does diminish the coherence of CRAN somewhat I'm not really favoring it, but I can see cases where this may be useful (e.g. I use a static vignette in one pkg to include a published paper). -Mark On Fri, Aug 30, 2019 at 5:00 PM Michael Dewey <li...@dewey.myzen.co.uk> wrote: > Comments in-line > > On 30/08/2019 14:59, Iñaki Ucar wrote: > > On Fri, 30 Aug 2019 at 15:26, J C Nash <profjcn...@gmail.com> wrote: > >> > >> I'm seeking some general advice about including vignettes in my > packages, > >> which are largely for nonlinear estimation and function minimization > (optimization). > >> This means that my packages offer alternatives to many other tools, and > the user > >> then has the chore of deciding which is appropriate. Bad choices can be > very > >> costly in inappropriate results or computational efficiencies. Hence, I > include > >> vignettes to offer comparisons and examples of use. > >> > >> Unfortunately, as in a case this week, changes in the comparison > packages break > >> my package(s), and I get an email from CRAN telling me to fix it before > some > >> date not far in the future. This means a) work for me, possibly at an > inopportune > >> time; b) risk of loss of capability, in the present case in the nlsr > package which > >> offers some unique capabilities, and c) extra work for CRAN for what > is, arguably, > >> updating of peripheral documentation. Updating optimization packages on > CRAN can be, > >> I have discovered, a very time-consuming task. Package optimx took over > 3 months > >> to get updated. > >> > >> It should be noted in the present situation that just before I got the > msg from > >> CRAN I got a msg from the maintainer of the package that has changed > and breaks > >> the vignette with some suggestions on a fix. The issue is that his > package has > >> changed function syntax -- a situation all of us know is fraught with > troubles, > >> since improvements may cause breakage. > >> > >> I am NOT saying that my vignettes should not be updated. However, I'm > wondering > >> if I should set up a repository for my vignettes on Github/Gitlab or > similar, and > >> simply link to them. This would separate the updating of vignettes from > the central > >> packages. Their updating could be less strictly tied to CRAN > activities, and could > >> also be a task undertaken by others who are not listed as maintainer. > >> > >> I'd welcome some (hopefully constructive) comments. Would CRAN > maintainers feel > >> this to be helpful, or does it lower the value of official R packages? > Do > >> other maintainers experience the same requests, or do they just not > include > >> vignettes (and many do not)? > > > > My two cents: > > > > For me, as a user, vignettes are the most valuable form of > > documentation in a package. Of course, this is personal opinion. > > Yes, but it is widely shared (in the sense that I think it too). > > I think the issue here is whether the intention is to compare with a > particular implementation of a technique in which case you probably do > need to do what you are currently doing or to compare with the technique > in general terms. If the latter then Iñaki's solution seems perfect to > me since even if the package interface changes it still implemented the > same technique (I assume). > > Michael > > But > > these days with so many good packages out there, I don't have time to > > install all of them and dive into the manual and the examples just to > > decide which one is better for my use case. A good written vignette > > most of the time is my driving factor (sometimes, if it's a small > > package with one particular functionality, a good README is enough, > > but that's not the case here). > > > > Thus, as a maintainer, I try to lead by example. It's time consuming, > > but on the other hand, many times a help request by a user can be > > resolved with "please, take a look at section x of vignette y". > > > > One thing I do to make them as maintainable as possible is to try to > > avoid dependencies on third-party packages as much as possible. In > > your case, comparing yourself with other alternatives may be > > important. I'd suggest to set eval=FALSE for chunks with expensive > > demonstrations of other packages, and then show a static figure with > > the comparison that you made once, but doesn't need to be recreated > > each time the vignette is built. In this way, issues like the one you > > described won't affect your package, at least immediately. Until some > > user reaches you to say, hey, I've tried the code in this vignette for > > package x and it doesn't work for me. Then it's time to revisit that > > code and rebuild the figure. > > > > You could have vignettes that you don't rebuild constantly in a > > separate repo and link them from a main vignette on CRAN, but that's > > no different from what I propose above, and it's one click away. > > > > Hope it helps. Regards, > > > > -- > Michael > http://www.dewey.myzen.co.uk/home.html > > ______________________________________________ > R-package-devel@r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-package-devel > [[alternative HTML version deleted]] ______________________________________________ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
