[R] Best Practices for submitting packages to CRAN

[Spencer Graves]

Two additions to Michael Friendly's comments:


       1.  Have you considered putting your package on R-Forge 
(r-forge.r-project.org)?  They have a facility (which has been broken 
for several months now but will likely be fixed again at some time in 
the future) to test your package more or less daily on 7 different 
combinations of operating system and versions of R.  This has 
occasionally found errors that I could not replicate -- but could 
nevertheless fix!  It also makes it easy for you to have people test a 
new version before you want to release it, e.g., via 
install.packages("fda", repos="http://R-Forge.R-project.org")' for the 
"fda" package.


       2.  In addition to "\dontrun", you can also put tests you DO want 
to perform but don't want to show the user in "\dontshow".  I use this 
latter routinely to do unit tests.  There is an RUnit package, which I 
probably should learn to use but haven't, and there are other unit 
testing facilities with R that others can discuss that can help you 
produce "trustworthy software" (John Chambers 2008 Software for Data 
Analysis, Springer).  Rather than learn these other facilities, I 
routinely program unit tests in the examples section of my help files, 
often using a construct like the following:


myAnswer <- myFun()

correctAnswer <- list(whatever)

\dontshow{stopifnot(}
all.equal(myAnswer, correctAnswer)
\dontshow{)}


       The code won't pass "R CMD check" until "myAnswer" and 
"correctAnswer" are essentially equal.


       When I find or someone reports a bug, I first program another 
check like this into the help file.  Then I fix the bug.  After that, I 
have confidence that if something other change introduces a problem like 
that, I'll know it before it reaches users other than me.


       sg


On 4/29/2011 8:12 PM, Michael Friendly wrote:
> On 4/28/2011 8:43 AM, Singmann wrote:
>> Dear all,
>>
>> I (and a colleague) have been working on our first package (for
>> fitting a
>> certain type of cognitive models:
>> http://www.psychologie.uni-freiburg.de/Members/singmann/R/mptinr) for
>> quite
>> a while now and have the feeling, that it is "good to go". That is,
>> we want
>> to submit it to CRAN. However, I still have two questions before
>> doing so
>> and would appreciate any comments.
>>
>> 1. How often is it appropriate to submit updated versions of your
>> package?
>> Background for this question: Although we think we have tested the
>> package
>> thoroughly, there are some errors that only pop up in daily use. That
>> is, it
>> could happen that, especially shortly after the release, fixes need
>> to be
>> released rather frequently (say, every 2 weeks). On the other hand, I
>> know
>> that humans have to operate CRAN and their time is limited.
>> Therefore, any
>> update will consume their time.
> You'll have to work out your own workflow for this, but a general
> practice might be to release a new version (with an incremented
> version number)  whenever you feel there are significant changes,
> particularly those that are user-visible or change usage.
>
> This assumes that your package passes R CMD check and R CMD build
> without errors or warnings, with the current version of R.
> If so, most of what happens on CRAN is automatic.  Otherwise
> you may provoke one of the trolls under the CRAN bridge or even
> a human.
>
> You might find it easier to register the project on R-Forge and
> do updates from there/
>
>>
>> 2. Is it necessary to put examples that take a considerable amount of
>> time
>> to run (>  1 hour) into a \dontrun block? Background: We have a
>> really slow
>> MCMC function. Some of the examples take ~1 hour to finish. If these
>> examples are run each time the package is checked, it will significantly
>> prolong the checking time. On the other hand, this check will ensure
>> that
>> all changes to the function do not corrupt it.
>
> Yes, do use \dontrun{ ... } for stuff in examples that is inconvenient
> or difficult to actually run each time during checking.  Sometimes
> people include the output from such dontrun examples as comments
> inside the example as in
>
> \dontrun{
> 1+1
> ## 2
> }
>
> But then the responsibility is yours to make sure that the examples
> still work after updates.
>
>>
>> --
>> View this message in context:
>> http://r.789695.n4.nabble.com/Best-Practices-for-submitting-packages-to-CRAN-tp3480870p3480870.html
>> Sent from the R help mailing list archive at Nabble.com.
>>
>
> ______________________________________________
> R-help at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-help
> PLEASE do read the posting guide
> http://www.R-project.org/posting-guide.html
> and provide commented, minimal, self-contained, reproducible code.
>


-- 
Spencer Graves, PE, PhD
President and Chief Operating Officer
Structure Inspection and Monitoring, Inc.
751 Emerson Ct.
San José, CA 95126
ph:  408-655-4567