General Issues

General issues and helpful notes around CRAN submission best practices.

Structure of CRAN-Submissions

Description Length

The description field in the DESCRIPTION file should be a short paragraph (2+ sentences) on the package’s purpose, motivation and may include further references to the package documentation website. You can also consider the Description length to be similar to a blurb or synopsis written on the inside jacket of a book - brief but informative. A good example of this description length is included in the ‘tidyverse’ package.

The Description field is intended to be a (one paragraph) description of what the package does and why it may be useful. Please add more details about the package functionality and implemented methods in your Description text.

Structuring of Examples

As part their documentation most functions have example code in their .Rd-files marked by the \examples{} tag. Examples serve two major purposes for packages on CRAN.

  1. Show users how to implement the function correctly and what to expect as outcome.
  2. Allow the CRAN team to perform test on the code.

For several reasons, some examples cannot be run as tests. Therefore, CRAN has several wrappers to structure them. The following list gives a short overview of the most common ones and when to use them.

  • Unwrapped:
    • Short examples to show the functionality of the code
    • CRAN recommends the use of toy examples on small data sets
    • Ideally, also cover some edge cases
  • \donttest{}:
    • Lengthy examples, with execution times longer than 5 seconds
    • Examples that download data
    • They are tested infrequently on CRAN as well and are also executed when calling example()
  • \dontrun{}:
    • Unexecutable examples due to missing information (e.g. API calls where a password is needed)
    • Examples which require additional software
    • Never executed, are automatically marked with a comment (“# Not run:”) in the Help file.
  • if(interactive()){}:
    • Functions which only run interactively and cannot be used in scripts
    • Most commonly, examples for Shiny Apps and interactive plots
  • try():
    • Examples which are supposed to fail and throw an error
    • try() shows the error message but won’t halt the execution
  • if(requireNamespace(“packagename”)){}
    • Used for examples which need particular packages to run
    • Those packages should be listed in the Suggests filed of the DESCRIPTION file
  • \dontshow{}:
    • Treated similarly to unwrapped examples but are not shown to the user
    • Great for setting and resetting options or code purely for tests
Important

All wrappers must still be placed inside the \examples{} tag.

\dontrun{} should only be used if the example really cannot be executed (e.g. because of missing additional software, missing API keys, …) by the user. That’s why wrapping examples in \dontrun{} adds the comment (“# Not run:”) as a warning for the user. Does not seem necessary. Please replace \dontrun with \donttest.

Please unwrap the examples if they are executable in < 5 sec, or replace \dontrun{} with \donttest{}.

Functions which are supposed to only run interactively (e.g. shiny) should be wrapped in if(interactive()). Please replace \dontrun{} with if(interactive()){} if possible, then users can see that the functions are not intended for use in scripts.

All your examples are wrapped in \donttest{} and therefore do not get tested.
Please unwrap the examples if that is feasible and if they can be executed in < 5 sec for each Rd file or create additionally small toy examples to allow automatic testing.

Package Size

Ideally, CRAN packages should be under 5 Mb. There are very few exceptions mostly for a larger inst/ folder (and these will trigger flags for every future submission). They must be approved by a CRAN team member and since every accepted version is saved on CRAN, they are very hesitant.

It’s best to minimize the package size. Large datasets can be hosted externally, such as on GitHub, and downloaded when necessary. Consider placing them in a separate data package that requires less frequent updates.

At a upper limit of the package tarball the CRAN policy states 10 Mb. It is recommended to include third-party source software within the package. If that requires larger tarballs, a modestly increased limit can be requested at submission.

Tip

If your package exceeds the recommended 5 Mb limit, it will generate a NOTE in the R CMD Check. You can explain why the size is okay by providing details in the cran-comments.md file.

A CRAN package should not be larger than 5 MB. Please reduce the size.

Communicating with CRAN

For a smooth review process and to provide CRAN volunteers with helpful context on any issues, it’s recommended to CC cran-submission@r-project.org in your email communications. See the rules and recommendations on the CRAN Repository Policy. This way, any available team member can respond. Additionally, include any updates or explanations related to your package in the submission comments file (cran-comments.md).

Back to top