Submitting packages to CRAN

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

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