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.

Keeping authorship stable

This section and the next one are based on a different package submission.

In order to update the disparityfilter package, I changed the authorship of the package to indicate my email address instead of the email address of the original author of the package, in order to handle the update of the package by myself.

Even though I changed the contact details of the package with the permission of its creator, the change was flagged during the package checks, and I had to revert that edit.

The best way to handle that issue is to indicate a different email during package submission, but to keep the author information in the DESCRIPTION file stable throughout package updates.

Refreshing the documentation

The checks run by CRAN will produce a WARNING flag any discrepancy between the documentation contained in .R files and the documentation contained in .Rd files.

These discrepancies occur as soon as you modify the slightest thing in your documentation, such as turning as_data_frame into igraph::as_data_frame to indicate the parent package of a function.

The WARNING that I received read as follows:

* checking for code/documentation mismatches ... WARNING
Codoc mismatches from documentation object 'backbone':
backbone
  Code: function(graph, weights = igraph::E(graph)$weight, directed =
                 igraph::is_directed(graph), alpha = 0.05)
  Docs: function(graph, weights = E(graph)$weight, directed =
                 is_directed(graph), alpha = 0.05)
  Mismatches in argument default values:
    Name: 'weights' Code: igraph::E(graph)$weight Docs: E(graph)$weight
    Name: 'directed' Code: igraph::is_directed(graph) Docs: is_directed(graph)

This mistake is avoidable only by refreshing the documentation before any package build, in order not to go through one more entirely avoidable email exchange with the CRAN maintainer—something that, again, I learnt by experiencing it firsthand.

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.

Update (March 25, 2016): the ggnetwork package is now available from CRAN. Thanks to the CRAN team, who flagged one last mistake about some CRAN URLs not being in their canonical form.

Update (April 30, 2016): added the last two sections about authorship and documentation. The disparityfilter package is also available from CRAN.

  • First published on March 24th, 2016