Submitting packages to CRAN
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.
This note lists a few of the mistakes that one can make before submitting a package to CRAN. The list is based on my own mistakes when submitting the ggnetwork
package to CRAN for the first time (see this other note for comments about the package itself).
Single quotes around package names
While the CRAN Repository Policy is short and straightforward enough, the manual page on Writing R Extensions is not such an easy read. The first mistake that I made in the DESCRIPTION file of my package was flagged as follows (links added):
Possibly mis-spelled words in DESCRIPTION:
ggplot (3:41, 8:54)
Please single quote software names.
Hadley Wickham’s R Packages book does not mention the issue, but the CRAN policy for the (mandatory) Title
and Description
fields of the DESCRIPTION file is clear on the topic, and reads as follows:
Refer to other packages and external software in single quotes, and to book titles (and similar) in double quotes.
This is likely to be a quite recent policy, as many packages available on CRAN do not follow it. However, many recent ggplot2-related packages do, including, for instance, the geomnet
and ggrepel
packages.
Title case for the Title
field
The other mistake that I made in my DESCRIPTION was not to “Title Case” its Title
field, which is a ridiculous mistake to make, since it is clearly mentioned both in Hadley Wickham’s instructions and in the CRAN policies:
The mandatory ‘Title’ field … should use title case (that is, use capitals for the principal words:
tools::toTitleCase
can help you with this)
For that mistake, I need to apologise to the CRAN team member (who also happens to be a member of the R Core Development team) who lost a few seconds here. In fact, I should have avoided the mistake entirely by using R-devel to check the package—more on that further down.
Vignette building and indexing
Bundling vignettes with a package is a great way to provide the user with an overview of the package, or with tutorials that cover specific functions. The mistake that I made at that stage read as follows:
Package has a VignetteBuilder field but no prebuilt vignette index.
I also need to apologise for that mistake, since I would not have made it if I had read Hadley Wickham on vignette metadata prior to submitting my package:
The first few lines of the vignette contain important metadata. The default template contains the following information:
--- title: "Vignette Title" author: "Vignette Author" date: "`r Sys.Date()`" output: rmarkdown::html_vignette vignette: > %VignetteIndexEntry{Vignette Title} %VignetteEngine{knitr::rmarkdown} usepackage[utf8]{inputenc} ---
The last four lines of metadata are crucial here, as they will ensure that the vignette will be compiled and moved into inst/doc
when the package itself is built. The last line of metadata might also be written as %VignetteEncoding{UTF-8}
.
Calling all non-base
functions
The last mistake that I made in my first submission of the package suprised me more than the previous ones, because it indicated that my automated checking of the package with R CMD CHECK
was imperfect:
* checking R code for possible problems ... NOTE fortify.igraph: no visible global function definition for 'installed.packages' Undefined global functions or variables: installed.packagesConsider adding
importFrom("utils", "installed.packages")to your NAMESPACE file.
An apology is also due here, as I believe that I made this mistake by being lazy and disregarding the boldened part of the following CRAN policy on package submission:
Please ensure that
R CMD check --as-cran
has been run on the tarball to be uploaded before submission. This should be done with the current version of R-devel (or if that is not possible and explained in the submission, current R-patched or the current release of R.)
Even though I did run R CMD CHECK
on the tarball of my package, I ran it using the current release of R, which loads several non-base
functions at startup, including the installed.packages
function from the utils
package.
Fixing the mistake was trivial: all it took was to add import the function as part of the documentation of the fortify.igraph
function, and to call the installed.packages
function as utils::installed.packages
in its code.
My guess is that I would have been able to flag that issue by using R-devel instead of the current release of R, but having still not bothered to install R-devel, I can only speculate that this would have been the case.
Lessons learned: before submitting a package to CRAN, carefully proofread the DESCRIPTION file and use devtools::build_win()
to check the package on Windows via CRAN, which should avoid common mistakes like those listed here.
R-bloggers.com offers daily e-mail updates about R news and tutorials about learning R and many other topics. Click here if you're looking to post or find an R/data-science job.
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.