CRAN_policies.texi

\input texinfo
@c %**start of header
@setfilename CRAN_policies.info
@settitle CRAN Repository Policy
@documentlanguage en

@set CRAN_POLICY_DATE $Date: 2018-12-04 02:37:15 -0600 (Tue, 04 Dec 2018) $
@set CRAN_POLICY_REVISION $Revision: 3953 $

@titlepage
@title CRAN Repository Policy
@c <FIXME>
@c Maybe there is a better way?
@c @subtitle Version @value{CRAN_POLICY_REVISION} (@value{CRAN_POLICY_DATE})
@subtitle Version @value{CRAN_POLICY_REVISION}
@c </FIXME>
@author CRAN Repository Maintainers
@end titlepage

@ifnottex
@c <FIXME>
@c Maybe there is a better way?
@c @center Version @value{CRAN_POLICY_REVISION}  (@value{CRAN_POLICY_DATE})
@center Version @value{CRAN_POLICY_REVISION}
@c </FIXME>

@center @b{CRAN Repository Maintainers}

@node Top, Preamble, (dir), (dir)

@menu
* Preamble::                    
* Source packages::             
* Binary packages::             
* Submission::                  
* Re-submission::               
@end menu

@end ifnottex

@node Preamble, Source packages, Top, Top
@unnumbered Preamble

This document describes the policies in place for the
@url{https://www.R-project.org/, R} package repository hosted by the
@url{https://CRAN.R-project.org/, Comprehensive R Archive Network}.  In
what follows, this @url{https://CRAN.R-project.org/web/packages/, 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 @url{https://www.R-project.org/foundation/index.html,
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).

@node Source packages, Binary packages, Preamble, Top
@unnumbered Source packages

@itemize @bullet

@item
The ownership of copyright and intellectual property rights of all
components of the package must be clear and unambiguous (including from
the authors specification in the @file{DESCRIPTION} file).  Where code
is copied (or derived) from the work of others (including from R
itself), care must be taken that any copyright/license statements are
preserved and authorship is not misrepresented.

Preferably, an @samp{Authors@@R} would be used with @samp{ctb} roles for
the authors of such code.  Alternatively, the @samp{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 @samp{cph} roles in the
@samp{Authors@@R} field, or using a @samp{Copyright} field (if necessary
referring to an @file{inst/COPYRIGHTS} file).

Trademarks must be respected.

@item
The package's @file{DESCRIPTION} file must show both the name and email
address of a single designated maintainer (a person, not a mailing
list).  That contact address must be kept up to date, and be usable for
information mailed by the CRAN team without any form of filtering,
confirmation @dots{}

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 @file{DESCRIPTION} fields could be used for providing email
addresses for contacting the package authors/developers (e.g.,
@samp{Contact}), or a URL for submitting bug reports (e.g.,
@samp{BugReports}).

Citations in the @samp{Description} field of the @file{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.

@item
Source packages may not contain any form of binary executable code.

@item
Source packages under an Open Source license must provide source or
something which can easily be converted back to source (e.g.,
@file{.rda} files) for all components of the package (including for
example PDF documentation, configure files produced by
@command{autoconf}). For Java @file{.class} and @file{.jar} files, the
sources should be in a top-level @file{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
@samp{Depends}, @samp{Imports} or @samp{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
@url{https://svn.r-project.org/R/trunk/share/licenses/license.db} will
generally not be accepted.

@item
Package authors should make all reasonable efforts to provide
cross-platform portable code.  Packages will not normally be accepted
that do not run on at least two of the major R platforms.  Cases for
Windows-only packages will be considered, but CRAN may not be the most
appropriate place to host them.

@item
Packages should be named in a way that does not conflict (irrespective
of case) with any current or past CRAN package (the
@url{https://CRAN.R-project.org/src/contrib/Archive/, Archive area} can be
consulted), nor any current @url{https://www.bioconductor.org/,
Bioconductor} package.  Package maintainers give the right to use that
package name to CRAN when they submit, so the CRAN team may orphan a
package and allow another maintainer to take it over.

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).

@item
Packages on which a CRAN package depends should be available from a
mainstream repository: if any mentioned in @samp{Suggests} or
@samp{Enhances} fields are not from such a repository, where to obtain
them at a repository should be specified in an
@samp{Additional_repositories} field of the @file{DESCRIPTION} file (as
a comma-separated list of repository URLs) or for other means of access,
described in the @samp{Description} field.

A package listed in @samp{Suggests} or @samp{Enhances} should be used
conditionally in examples or tests if it cannot straightforwardly be
installed on the major R platforms.

@item
CRAN versions of packages should work with the current CRAN and 
Bioconductor releases of dependent packages and not anticipate nor 
recommend development versions of such packages on other repositories.

@item
Packages will not normally be removed from CRAN: however, they may
be archived, including at the maintainer's request.

Packages for which @command{R CMD check} gives an @samp{ERROR} when a
new R @math{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 @math{x.y.0}
release.  Packages which are not updated are liable to be archived.

@item
Packages should be of the minimum necessary size.  Reasonable
compression should be used for data (not just @file{.rda} files) and PDF
documentation: CRAN will if necessary pass the latter through
@command{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.,
@file{.jar} files.

@item
Checking the package should take as little CPU time as possible, as the
CRAN check farm is a very limited resource and there are thousands of
packages.  Long-running tests and vignette code can be made optional for
checking, but do ensure that the checks that are left do exercise all
the features of the package.

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.

@item
Packages which use Internet resources should fail gracefully with an
informative message if the resource is not available (and not give a
check warning nor error).

@item
The code and examples provided in a package should never do anything
which might be regarded as malicious or anti-social.  The following are
illustrative examples from past experience.

@itemize @minus

@item
Compiled code should never terminate the R process within which it is
running.  Thus C/C++ calls to @code{assert}/@code{abort}/@code{exit},
Fortran calls to @code{STOP} and so on must be avoided.  Nor may R code
call @code{q()}.

@item
A package must not tamper with the code already loaded into R: any
attempt to change code in the standard and recommended packages which
ship with R is prohibited.  Altering the namespace of another package
should only be done with the agreement of the maintainer of that
package.

@item
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 @env{TMPDIR}: and such usage should be cleaned up).
Installing into the system's R installation (e.g., scripts to its
@file{bin} directory) is not allowed.

Limited exceptions may be allowed in interactive sessions if the
package obtains confirmation from the user.

@item
Packages should not modify the global environment (user's workspace).

@item
Packages should not start external software (such as PDF viewers or
browsers) during examples or tests unless that specific instance of
the software is explicitly closed afterwards.

@item
Packages should not send information about the R session to the
maintainer's or third-party sites without obtaining confirmation from
the user.

@item
Packages must not disable the stack-checking mechanism in the R process
into which they are loaded.

@item
@acronym{CRAN} packages should use only the public API.  Hence they
should not use entry points not declared as API in installed headers nor
@code{.Internal()} nor @code{.Call()} etc calls to base packages. Also,
@code{:::} 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.

@item
Packages should not attempt to disable compiler diagnostics.

@end itemize

@item
Changes to @acronym{CRAN} packages causing significant disruption to
other packages must be agreed with the @acronym{CRAN} maintainers well
in advance of any publicity.  Introduction of packages providing
back-compatibility versions of already available packages is not
allowed.

@item
Downloads of additional software or data as part of package installation
or startup should only use @emph{secure} download mechanisms (e.g.,
@samp{https} or @samp{ftps}).

@end itemize

@node Binary packages, Submission, Source packages, Top
@unnumbered Binary packages

Policies for when a (Windows or macOS) binary package will be distributed:

@itemize

@item
all its package dependencies on CRAN are available for that platform.
Dependencies from other repositories will be installed at CRAN's
discretion.

@item
any external software needed can easily be installed on the build
machine for all the sub-architectures: here ``easily'' includes not
depending on specific versions, nor should the installed binary depend
on specific versions.

@item
it passes @command{R CMD check} without error for all the available
sub-architectures, or at CRAN's discretion, for the most important
sub-architecture(s).

@end itemize

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 (macOS) and Uwe Ligges (Windows); email
addresses @samp{@var{First.Lastname}@@R-project.org}.

@node Submission, Re-submission, Binary packages, Top
@unnumbered Submission

When submitting a package to CRAN you should use the submission form at
@uref{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 @uref{ftp://CRAN.R-project.org/incoming/}.  Submission
difficulties (such as non-receipt of the confirmation email) can be
discussed with @email{cran-sysadmin@@R-project.org}.

In more detail:

@itemize

@item
All correspondence with CRAN must be sent to @code{CRAN-submissions@@R-project.org}
(not members of the team) and be in plain text ASCII (and not HTML).

@item
Uploads must be source tarballs created by @command{R CMD build} and
following the @file{@var{PACKAGE}_@var{VERSION}.tar.gz} naming scheme.
This should be done with current R-patched or the current release of R.

@item
Please ensure that @command{R CMD check --as-cran} has been run @emph{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 @code{Description} field. See
@uref{submission_checklist.html} for details.

In principle, packages must pass @command{R CMD check} without warnings or
significant notes to be admitted to the main @acronym{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 @uref{URL_checks.html}.

@item
For a package update, please check that any packages depending on this
one still pass @command{R CMD check}: it is especially expected that you
will have checked your own packages.  Reverse dependencies can
conveniently be checked using @code{tools::check_packages_in_dir(reverse
= list())}, and changes in check status subsequently be analyzed using
@code{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
@code{tools::package_dependencies(reverse = TRUE)}.

@item
If for some reason the submission has to be made by someone else (for
example, a co-author) this needs to be explained, and the designated
maintainer will need to confirm the submission.

@item
Explain any change in the maintainer's email address and if possible
send confirmation from the previous address (by a separate email to
@code{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.

@item
Do not email the package itself.

@item
Once uploaded, no further submissions of that package should be made
whilst the uploaded version is pending processing (which may take a
few days) and you have not received a reply from a CRAN maintainer.

@item
Part of the processing is that uploads may be renamed by adding one of
the extensions @file{.nowebform}, @file{.pending} or @file{.noemail}:  the
presence of such a file is a sign that the submission process is not 
finished yet and CRAN maintainers are waiting for response or 
resubmission from the package maintainer (and such a file name should 
never be uploaded).

@item
Submitting updates should be done responsibly and with respect for the
volunteers' time.  Once a package is established (which may take several
rounds), ``no more than every 1--2 months'' seems appropriate.

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
@url{https://win-builder.R-project.org/, winbuilder} service to
check a package before submission.  There is a lot of helpful advice on
writing portable packages in @url{../../manuals.html#R-exts,
``Writing R Extensions''}.

Before submitting a package update, consult the CRAN check page at
@samp{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.

@item
If an update will change the package's API and hence affect packages
depending on it, it is expected that you will contact the maintainers of
affected packages and suggest changes, and give them time (at least 2
weeks, ideally more) to prepare
updates before submitting your updated package.  Do mention in
the submission email which packages are affected and that their
maintainers have been informed.
In order to derive the reverse dependencies of a package including the 
addresses of maintainers who have to be notified upon changes, the 
function @url{https://developer.R-project.org/CRAN/Scripts/depends.R, 
reverse_dependencies_with_maintainers} is available from the developer 
website. 

@end itemize

@node Re-submission,  , Submission, Top
@unnumbered Re-submission

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
@uref{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.)

@bye