• Preamble: | ||
• Source packages: | ||
• Binary packages: | ||
• Submission: | ||
• Re-submission: |
Next: Source packages, Previous: Top, Up: Top
This document describes the policies in place for the R package repository hosted by the Comprehensive R Archive Network. In what follows, this CRAN package repository will be referred to as “CRAN”.
CRAN is maintained by the efforts of volunteers (the “CRAN team”) and the resources of the R Foundation and the employers of those volunteers (WU Wien, TU Dortmund, U Oxford, AT&T Research). Having a package distributed by CRAN is subject to a set of policies, and submitting a package (including an update) to CRAN indicates agreement to these policies.
CRAN hosts packages in publication quality and is not a development platform. A package’s contribution has to be non-trivial.
Distributing code or documentation is subject to legal requirements, and CRAN operates in many jurisdictions. One of the aims of these policies is to ensure that the distributors meet their legal obligations of diligence without excessive work.
The time of the volunteers is CRAN’s most precious resource, and they reserve the right to remove or modify packages on CRAN without notice or explanation (although notification will usually be given).
Next: Binary packages, Previous: Preamble, Up: Top
Preferably, an ‘Authors@R’ would be used with ‘ctb’ roles for the authors of such code. Alternatively, the ‘Author’ field should list these authors as contributors.
Where copyrights are held by an entity other than the package authors, this should preferably be indicated via ‘cph’ roles in the ‘Authors@R’ field, or using a ‘Copyright’ field (if necessary referring to an inst/COPYRIGHTS file).
Trademarks must be respected.
The maintainer warrants that (s)he is acting on behalf of all credited authors and has their agreement to use their material in the way it is included in the package (or if this is not possible, warrants that it is used in accordance with the license granted by the original author).
Additional DESCRIPTION fields could be used for providing email addresses for contacting the package authors/developers (e.g., ‘Contact’), or a URL for submitting bug reports (e.g., ‘BugReports’).
Citations in the ‘Description’ field of the DESCRIPTION file should be in author-year style, followed by a DOI or ISBN for published materials, or a URL otherwise. Preferably, the year and identifier would be enclosed, respectively, in parentheses and angle brackets.
autoconf
). For Java .class and .jar files, the
sources should be in a top-level java directory in the source
package (or that directory should explain how they can be obtained).
Such packages are not permitted to require (e.g., by specifying in ‘Depends’, ‘Imports’ or ‘LinkingTo’ fields) directly or indirectly a package or external software which restricts users or usage.
The package’s license must give the right for CRAN to distribute the package in perpetuity. Any change to a package’s license must be highlighted when an update is submitted (for there have been instances of an undocumented license change removing even the right of CRAN to distribute the package).
Packages with licenses not listed at https://svn.r-project.org/R/trunk/share/licenses/license.db will generally not be accepted.
When a new maintainer wishes to take over a package, this should be accompanied by the written agreement of the previous maintainer (unless the package has been formally orphaned).
A package listed in ‘Suggests’ or ‘Enhances’ should be used conditionally in examples or tests if it cannot straightforwardly be installed on the major R platforms.
Packages for which R CMD check
gives an ‘ERROR’ when a
new R x.y.0 version is released will be archived (or in
exceptional circumstances updated by the CRAN team) unless the
maintainer has set a firm deadline for an upcoming update (and keeps to
it).
Maintainers will be asked to update packages which show any warnings or significant notes, especially at around the time of a new x.y.0 release. Packages which are not updated are liable to be archived.
qpdf
.
As a general rule, neither data nor documentation should exceed 5MB (which covers several books). A CRAN package is not an appropriate way to distribute course notes, and authors will be asked to trim their documentation to a maximum of 5MB.
Where a large amount of data is required (even after compression), consideration should be given to a separate data-only package which can be updated only rarely (since older versions of packages are archived in perpetuity).
Similar considerations apply to other forms of “data”, e.g., .jar files.
If running a package uses multiple threads/cores it must never use more than two simultaneously: the check farm is a shared resource and will typically be running many checks simultaneously.
Examples should run for no more than a few seconds each: they are intended to exemplify to the would-be user how to use the functions in the package.
assert
/abort
/exit
,
Fortran calls to STOP
and so on must be avoided. Nor may R code
call q()
.
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.
Limited exceptions may be allowed in interactive sessions if the package obtains confirmation from the user.
.Internal()
nor .Call()
etc calls to base packages. Also,
:::
should not be used to access undocumented/internal objects in
base packages (nor should other means of access be employed). Such
usages can cause packages to break at any time, even in patched versions
of R.
Next: Submission, Previous: Source packages, Up: Top
Policies for when a (Windows or OS X) binary package will be distributed:
R CMD check
without error for all the available
sub-architectures, or at CRAN’s discretion, for the most important
sub-architecture(s).
Binary packages are not accepted from maintainers: CRAN will only host binary packages prepared by those responsible for the binary areas. Their packages are made automatically by batch jobs and can take a day or two to appear on the CRAN master site (maybe longer to reach CRAN mirrors).
Binary packages are built for the current version of R: they may also be built for the last version in the previous series (e.g. R 3.1.3 when R 3.2.x is current) or for R-devel.
Questions about binary packages should be addressed to those responsible for building them: Simon Urbanek (OS X) and Uwe Ligges (Windows); email addresses ‘First.Lastname@R-project.org’.
Next: Re-submission, Previous: Binary packages, Up: Top
When submitting a package to CRAN you should use the submission form at https://CRAN.R-project.org/submit.html (and not send an email). You will be sent a confirmation email which needs to be accepted.
You can check that the submission was received by looking at ftp://CRAN.R-project.org/incoming/. Submission difficulties (such as non-receipt of the confirmation email) can be discussed with cran-sysadmin@R-project.org.
In more detail:
CRAN-submissions@R-project.org
(not members of the team) and be in plain text ASCII (and not HTML).
R CMD build
and
following the PACKAGE_VERSION.tar.gz naming scheme.
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.)
For new submissions in particular, please take care to include an
informative Description
field. See
submission_checklist.html for details.
In principle, packages must pass R CMD check
without warnings or
significant notes to be admitted to the main CRAN package
area. If there are warnings or notes you cannot eliminate (for example
because you believe them to be spurious) send an explanatory note as
part of your covering email, or as a comment on the submission form.
For interpretation of the URL checks, see URL_checks.html.
R CMD check
: it is especially expected that you
will have checked your own packages. Reverse dependencies can
conveniently be checked using tools::check_packages_in_dir(reverse
= list())
, and changes in check status subsequently be analyzed using
tools::check_packages_in_dir_changes()
. A listing of the reverse
dependencies of the current version can be found on the CRAN web page
for the package, or be obtained via
tools::package_dependencies(reverse = TRUE)
.
CRAN-submissions@R-project.org
) or explain why it is not possible.
If the package needs special treatment (for example if vignettes can only be run or re-built on the maintainer’s machine or take a very long time), say so on the submission form.
Authors can avoid a lot of the all too frequent rounds of updates by checking carefully for themselves. It should be normal for those without Windows machines of their own to use the winbuilder service to check a package before submission. There is a lot of helpful advice on writing portable packages in “Writing R Extensions”.
Before submitting a package update, consult the CRAN check page at ‘https://CRAN.R-project.org/web/checks/check_results_NAME.html’, substituting NAME by the name of your package. In particular, wait for that page to be fully updated after publication of a version (which can take at least 48 hours) before submitting any corrections.
Previous: Submission, Up: Top
Re-submission is done in the same way as submission, using the ‘Optional comment’ field on the webform (and not a separate email) to explain how the feedback on previous submission(s) has been addressed.
Updates to previously-published packages must have an increased version number unless a ‘same-version update’ is requested by the maintainers. Increasing the version number at each submission reduces confusion so is preferred even when a previous submission was not accepted.
For packages which have recently been archived, a snapshot of the CRAN results page at the time of archival may be available under https://cran-archive.r-project.org/web/checks/. (Note that only a few of the links from the snapshot will work: normally those to listed ‘Alternative issues’ will.)