Someone asked recently about tips for package development workflow to optimize a successful submission to CRAN.
The ultimate guide is probably Hadley’s book on package development, but here’s more of a bulleted list of some things I do.
Choice of text editor/IDE is always contentious, but for R package development, RStudio makes it so easy, including keyboard shortcuts for lots of steps that you need to make development faster. See the cheatsheet.
Documentation and roxygen2
You can always write your manual files (
.Rd) files by hand, but to avoid mistakes including missing and duplicate parameter definitions, and other things, simply write documentation alongside your code with roxygen2. The RStudio IDE includes a keyboard shortcut (shift+cmd+D on Mac) to generate manual files from your roxygen documentation.
When you run either
R CMD CHECK in your terminal or
devtools::check() or simply using keyboard shortcuts in RStudio, you may notice problems with documentation, upon which you can make fixes, quickly re-document the whole package, then run check again. Iterating on this process is very easy with RStudio keyboard shortcuts.
CRAN checks now actually run code examples wrapped in
\donttest. So if you have examples that may throw warnings or errors on purpose or accident, make sure to wrap them in
\dontrun. Ripley used to complain that at least some examples in the package should run on check, but I haven’t heard this complaint in a while.
First submission of the package?
If it is your first submission of the package:
- Include the sentence in your submission I have read and agree to the the CRAN policies at http://cran.r-project.org/web/packages/policies.html
CRAN maintainers generally don’t look at code in my experience, but they may in the case of some examples or tests not passing on submission.
If you have tests in your package, and you should, think about whether your tests are likely to fail in some scenarios. For example, I mostly write packages that work with web APIs, all of which are not under my control, meaning they could fail at any time, causing tests to fail on CRAN (CRAN runs check once per day I think).
If you do have tests may fail, think about ignoring tests all together on CRAN. If you do this, it’s especially important to use continuous integration on your own. For example, use Travis-CI, which will run check on your package on each change. If you have a package that works with web APIs, it’s important to check your package functionality even when you aren’t changing it since the resource your package works with can change. So run tests e.g. once per day - you can do something like we do using a bit of Ruby code.
I just talked about this above, but a few more thoughts. This is a relatively easy thing to do, its free, and at least I think it greatly pays off once set up. In addition, you can do more than just test code, and run checks. You can deploy artifacts to various places. That is, for example, you could at the end of a build on Travis-CI, push a binary of the package to Dropbox, or Amazon S3. A few good options that I’ve used:
- Travis-CI (R integration) - Linux/unix builds
- Appveyor (R integration) - Windows builds
There are other options, but I haven’t used them…
In addition to following CRAN’s guidelines (and search description in the CRAN policies), some tips for some of the parts of the file.
- Title: must be sentence case, no period at end
- Description: Don’t use the phrase This package
- Watch out for possibly mis-spelled words warnings on check. They will reject your package for very minor mis-spellings.
Use cran-comments.md file
Hadley supports this in
devtools. Put a file named
cran-comments.md in the root of your package. In this file, include the comments you would submit for the package (e.g., I agree to cran policies…this package passed all checks…etc). Rembmer to put
cran-comments.md in the
.Rbuildignore file in the root of your package so that
R CMD CHECK doesn’t complain. When you use the
devtools::release() function, it will look for this file, and automatically throw in your submission comments. Doing this and using
release() means you don’t have to worry about Brian Ripley complaining about rich text emails.
CRAN policy changes
If you’re on Twitter, watch the
#rstats hashtag to be more likely to notice any upcoming changes in package submission policies. Also can follow Dirk’s CRAN policy watch repo.