DESCRIPTION File Issues

The DESCRIPTION Files Issues chapter features recipes on content formatting, license structuring, and how to include additional background context & links.

Formatting Software Names

Problem

The automatic spell check has flagged a software name as incorrect and results in a NOTE.

Solution

All references to names of software, packages and API names in the description section of the DESCRIPTION file should be wrapped in single quotes. e.g.: ‘ggplot2’, ‘Python’, etc.

Details

Please always write package names, software names and API (application programming interface) names in single quotes in title and description. e.g: –> ‘python’

Please note that package names are case sensitive.

Words in single quotes are not flagged by the automatic spell check and may be used when appropriate to include references to software names only.

The description section in the DESCRIPTION file of the ‘readr’ package provides an example which uses single quotes around the package name and file extensions:

Description: The goal of 'readr' is to provide a fast and friendly way to
    read rectangular data (like 'csv', 'tsv', and 'fwf').  It is designed
    to flexibly parse many types of data found in the wild, while still
    cleanly failing when data unexpectedly changes.

Explaining Acronyms

Problem

You are using acronyms in your DESCRIPTION file or they are flagged by the automatic spell check.

Solution

Document all non-obvious acronyms in the cran-comments.md file to facilitate the CRAN team review.

Details

Please always explain all acronyms in the description text.

Most acronyms that are not widely known should be explained. For example, you don’t have to explain OLS, SEO, or DNA but explanations should be provided for: MEFM or OCCDS. If you are unsure of the acronyms common knowledge, please document all acronyms in the package.

LICENSE files

Problem

Some licenses do not need to be added verbatim, instead they are referenced in the DESCRIPTION file and the CRAN template is added to the package. You can find the template at the CRAN website.

Solution

Remove the reference + file LICENSE and delete the LICENSE file.

Details

The LICENSE file is only needed if you have additional restrictions to the license which you have not? In that case omit the file and its reference in the DESCRIPTION file.

License components with restrictions and base license permitting such: GPL-3 + file LICENSE

We do not need “+ file LICENSE” and the file as these are part of R. This is only needed in case of attribution requirements or other possible restrictions. Hence please omit it.

Most licenses don’t need an additional file as these are part of R. The list of which licenses that do require an additional file can be accessed within R by searching for Note: this is a template, needs + file LICENSE:

path_licenses <- list.files(path = R.home(), "license.db", full.names = TRUE, recursive = TRUE)
licenses_doc <- as.data.frame(read.dcf(path_licenses))

If an additional file is needed, it should only specify the author and year for a MIT file or year, copyright holder, and organization for a BSD file.

Tip

Licenses should be FOSS, or allowed by R.

Title Case

Problem

The package Title field in the DESCRIPTION file is not in Title Case and the first letter of some or all of the words in the title are lowercase.

Solution

The package Title field in the DESCRIPTION file must be in Title Case, except words like “a”, “the” or “of”.

Details

The Title field should be in title case. Current version is:
‘This is my title’

In title case that is:
‘This is My Title’

Determining Title Case automatically can be challenging due to word significance being only known by the package author. The function toTitleCase() can assist with transforming sentences into Title Case from the ‘tools’ package.

tools::toTitleCase("web application framework for R")
[1] "Web Application Framework for R"
Note

There are some exceptions to using Title Case for quoting longer works like book titles and shorter works like research papers.

It is also not recommended to mention package names in the Title.

Using Authors@R

Problem

You have not properly declared the authors, maintainers and copyright holders in the Authors@R section of the DESCRIPTION file.

Solution

Add the Authors@R field in the DESCRIPTION file.

Details

Author field differs from that derived from Authors@R.

No Authors@R field in DESCRIPTION.
  Please add one, modifying
    Authors@R: c(person(given = “Alice”,
      family = “Developer”,
      role = c(“aut”, “cre”),
      email = “alice.developer@some.domain.net”),
    person(given = “Bob”,
      family = “Dev”,
      role = “aut”),
    )
  as necessary.

You can find more roles in the help documentation by running ?utils::person. Make sure the provided email address is actively monitored, as it will be the primary point of contact with CRAN for future updates and fixes.

Authors@R: person("Jane", "Smith", email = "chef@cran-cookbook.com",
  role = c("aut", "cre"), ORCID = "<USER-ORCID>")
Note

The Maintainer and Author fields are automatically generated, so you don’t need to add them manually.

If your package uses the older approach of specifying Maintainer and Author separately in the DESCRIPTION file, it won’t be rejected for that reason alone. However, this method is discouraged, and any manual modifications that differ from the auto-generated fields will result in automatic rejection by CRAN.

References

Problem

The reference link in the Description field is incorrectly formatted or isn’t clickable.

Solution

Remove the space after <doi:…> or <https:…> to enable the reference link. Write the reference in the form: Authors (year) <doi:…>.

Details

If there are references describing the methods in your package, please add these in the description field of your DESCRIPTION file in the form
authors (year) <doi:…>
authors (year, ISBN:…)
or if those are not available: <https:…>
with no space after ‘doi:’, ‘https:’ and angle brackets for auto-linking. (If you want to add a title as well please put it in quotes: “Title”)

Ideally, each package should include at least one reference in the description text to help users further explore the theory behind the package. These references should be formatted as shown in the ‘Rcpp’ package:

Description: The 'Rcpp' package provides R functions as well as C++ classes which
 offer a seamless integration of R and C++. Many R data types and objects can be
 mapped back and forth to C++ equivalents which facilitates both writing of new
 code as well as easier integration of third-party libraries. Documentation
 about 'Rcpp' is provided by several vignettes included in this package, via the
 'Rcpp Gallery' site at <https://gallery.rcpp.org>, the paper by Eddelbuettel and
 Francois (2011, <doi:10.18637/jss.v040.i08>), the book by Eddelbuettel (2013,
 <doi:10.1007/978-1-4614-6868-4>) and the paper by Eddelbuettel and Balamuta (2018,
 <doi:10.1080/00031305.2017.1375990>); see 'citation("Rcpp")' for details.
Tip

Including a reference in the Description field is optional, and your package will not be archived if one is missing. You can also use the cran-comments.md file to provide additional references or information.

Back to top