An open and collaborative list of things you have to check before submitting your package to the CRAN.
This repo was born after exchanges on Twitter regarding the CRAN submission process, especially this thread.
The idea here is to collect ground rules that would help the CRAN doing there work more easily, by listing common (or uncommon) things that they ask maintainers to change in order to be CRAN-proof.
CRAN submission is strict, the CRAN team is doing its work voluntarily, and there are more than 15K packages to maintain.
We believe we can help them by giving some good practices about package development and CRAN submission, so that package authors can work on these issues before the CRAN team ask them to do so. Hence, we could save everyone time by preventing the CRAN team from sending you an email because there is "with R" in the title of your DESCRIPTION. Because, as said by Peter Dalgaard:
too many people do not realise that the CRAN maintainer group can be counted on one hand, even one finger at times.
The first thing to do is to run devtools::check(), and to be sure that there are no error, no warning, no note.
If you're in RStudio, you can also click on Build > Check.
If ever you think these warnings or notes are not justified, leave a comment when submitting where you specify why you think this is not justified.
You can call usethis::use_spell_check() inside your package to add a test for spelling.
Call spelling::spell_check_package() at any time if you need to run the spellcheck.
The {rhub} package and API allow you to check your package on several platforms, and for CRAN with rhub::check_for_cran().
More about {rhub}: https://github.com/r-hub/rhub
Test that your package builds using the win-builder tool, or with devtools::check_win_devel().
See https://github.com/DavisVaughan/extrachecks
These checks might not catch everything the CRAN team will catch, so here is a list of good practices:
Note that if this is your first submission, you will automatically have a NOTE, for New submission.
CRAN submission of a new version should not be done too frequently. One time every 30 days seems to be the general rule (unless you're resubmitting after a CRAN team member feedback).
When resubmitting after a CRAN feedback, be sure to include that this is a resubmission after a feedback, and describe what you have done.
If you resubmit after a CRAN feedback, add 1 to the patch component of your version number (e.g, if your first submission is 0.3.1, your resubmission should be 0.3.2).
CRAN can reject packages that have grammar errors on the DESCRIPTION.
Some common spelling errors:
- Other packages should be between
'(example:Lorem-Ipsum Helper Function for 'shiny' Prototyping) - Acronyms should be capitalized (example:
API, notApi)
DESCRIPTION file should have a cph (copyright holder).
It can either be the first author, or the company where the author(s) work(s).
This might not be caught by the CRAN, but be sure you have filled everything in this file.
It's tempting to write something like 'A friendlier condition handler for R' or 'Easy Dockerfile creation for R' in the title of your repository on GitHub (and seems appropriate). The CRAN team will ask you to remove this, as it is redundant (you're only dealing with R packages on the CRAN).
Write an elaborated Description field.
The title should be in title case
Note: this should be caught by r-hub.
A CRAN-proof package should have a long description that explains what the package does, what are the benefits, what is new and how does it differ from what is already on the CRAN.
Neither the title nor the description should start with "A package..." or with the name of the package.
If you quote another package, an article/book or a website/API, put its name between single quote '.
If a function name is used in your DESCRIPTION, make sure to follow it with parentheses. e.g., "provides a drop-in replacement for cat() from the 'base' package."
If you write an R interface to an API or implement an algorithm from a published article/book, add a reference to the publication as a DOI, ISBN, or similar canonical link, or URL for the API or article in the 'Description' field of your DESCRIPTION file.
When linking to an article or website in the DESCRIPTION, use angle brackets to auto-link.
API name <http:...> or <https:...>
authors (year) <DOI:...> (see <https://en.wikipedia.org/wiki/Digital_object_identifier> )
authors (year) <arXiv:...>
authors (year, ISBN:...)
with no space after https:, doi:, arXiv: and angle brackets for auto-linking.
All the exported functions in your package should have a @return value.
If a function does not return a value, document that too.
\dontrun{} elements in the examples might in fact be run by CRAN.
If you don't want an example to be run, wrap it between if (interactive()) {}.
If there are some URLs in your documentation, be sure to:
- use https
- use the canonical form for CRAN package (i.e.: https://CRAN.R-project.org/package=***)
- use canonical form for Bioconductor package (i.e.: https://bioconductor.org/packages/***)
If you have examples that take more than a few seconds each to run, wrap them in \donttest{}, don't use dontrun{}.
#' @example
#' \donttest{x <- foo(y)}
There should be no empty tags in the documentation (for the one requiring a value).
CRAN Repository Policy state :
Packages should not write in the user’s home filespace (including clipboards), nor anywhere else on the file system apart from the R session’s temporary directory (or during installation in the location pointed to by TMPDIR: and such usage should be cleaned up). Installing into the system’s R installation (e.g., scripts to its bin directory) is not allowed.
You might not know what temporary directories / files are or how to use them. These temporary files are created for the current R session, and they are deleted when the session is closed.
You can create them with:
file <- tempfile()
Add an extension with
tmp <- tempfile(fileext = ".csv")
tmp
[1] "/var/folders/lz/thnnmbpd1rz0h1tmyzgg0mh00000gn/T//Rtmpnh8kAc/fileae1e28878432.csv"
So you can:
write.csv(iris, file = tmp)
See: Create Names for Temporary Files
If packages depend on your package, you should run a reverse dependencies test with devtools::revdep().
Creates cran-comments.md, a template for your communications with CRAN when submitting a package. The goal is to clearly communicate the steps you have taken to check your package on a wide range of operating systems. If you are submitting an update to a package that is used by other packages, you also need to summarize the results of your reverse dependency checks.
usethis::use_cran_comments(open = rlang::is_interactive())
You can run devtools::release() to automatically send to CRAN from R.
You'll receive a link in your mailbox. Click on this link to confirm the upload.
Depending on the package, it might take between one hour and several weeks, if it needs manual inspection, it can take some time.
You can watch the status of your package with {cransays}: https://lockedata.github.io/cransays/articles/dashboard.html
-
R packages - by Hadley Wickham & Jennifer Bryan
-
Writing R Extensions - Official Documentation
-
Mastering Software Development in R - by Roger D. Peng, Sean Kross, and Brooke Anderson.
-
How to develop good R packages (for open science) - by Maëlle Salmon (including list of tutorials)
-
Sinew: Simple R Package Documentation - by Jonathan Sidi
-
rOpenSci Packages: Development, Maintenance, and Peer Review - by rOpenSci onboarding editors