Best Practices for submitting packages to CRAN

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Best Practices for submitting packages to CRAN

Singmann
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.

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.

Thank you for taking your time,

Henrik
Reply | Threaded
Open this post in threaded view
|

Re: Best Practices for submitting packages to CRAN

Michael Friendly
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.
>

______________________________________________
[hidden email] 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.
Reply | Threaded
Open this post in threaded view
|

Re: Best Practices for submitting packages to CRAN

Spencer Graves-2
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.
>>
>
> ______________________________________________
> [hidden email] 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

______________________________________________
[hidden email] 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.