Publishing to CRAN

The ownership of copyright and intellectual property rights of every component of the package has to be clear, including the components downloaded at installation or during use. In the DESCRIPTION file that means an Authors@R field, which Writing R Extensions says is required for CRAN submissions, built with person() and the role codes: aut for an author, cre for the maintainer, ctb for a contributor and cph for a copyright holder. Code copied or derived from other work keeps its copyright and licence statements and its authors, preferably as ctb entries. Where the copyright belongs to someone other than the authors, the policy asks for cph entries in Authors@R, or for a Copyright field that may refer to a file inst/COPYRIGHTS. An ORCID or ROR identifier goes into the comment argument of person(), which CRAN strongly encourages.

There must be one designated maintainer, a person and not a mailing list, with a name and a valid email address that stays current and is usable without filtering, confirmation steps or forwarding, because the CRAN team and the automatic systems write to that address. The maintainer warrants that they act for all credited authors. The licence has to give CRAN the right to distribute the package in perpetuity, licences that are not in the licence database shipped with R (license.db) are generally refused, and a change of licence has to be highlighted in the next submission. The shelf package follows all of this with the placeholder maintainer maintainer@example.com, one person() carrying the roles aut, cre and cph, and License: MIT + file LICENSE.

Source: Writing R Extensions: The DESCRIPTION file

The LICENSE file written by usethis::use_mit_license() holds two lines, YEAR: 2026 and COPYRIGHT HOLDER: shelf authors, which is the form that the + file LICENSE part of the field refers to; the longer LICENSE.md the same function writes is left out of the tarball through .Rbuildignore. The text fields have conventions of their own, which the incoming check enforces and which the section on the incoming checks below shows failing: the Title is in title case, at most about 65 characters, without a final period and without repeating the package name; the Description is one paragraph of complete sentences that does not start with the package name or "This package"; names of other packages and external software are in single quotes, function names are written with parentheses and without quotes, citations are in author-year style with a DOI in angle brackets, and URLs are in angle brackets too. The next script reads those facts back from the shelf tree with desc 1.4.3; tools::toTitleCase() does the capitalisation for you when you are unsure how to write a title.

Source: Writing R Extensions: The DESCRIPTION file

The policy lists behaviour that a package must avoid because CRAN checks run unattended on shared machines and a package is code that runs on other people’s computers. It must not write anywhere in the user’s file space (the home directory and the clipboard included) apart from the temporary directory of the R session, and what it writes there has to be cleaned up. Since R 4.0.0 a package that must keep data, configuration or a cache between sessions may use the per-package user directories returned by tools::R_user_dir(), provided it needs a version dependency on R (>= 4.0) or uses the function conditionally, keeps the files small and removes outdated material. A package must not modify the global environment (the workspace), must not call q(), must not tamper with the code of the standard and recommended packages, must not use ::: or .Internal() and .Call() entry points that base R does not declare as API, must not start external programs such as viewers or browsers during examples and tests without closing them, must not send information about the session to third parties without the user’s confirmation, and must not turn off security provisions such as the verification of TLS certificates. Downloads of anything at installation or startup use https and, for more than a few megabytes, a large enough timeout.

Source: R documentation: R_user_dir

Two limits are checked mechanically. A package must never use more than two cores at the same time, and R CMD check --as-cran sets the environment variable _R_CHECK_LIMIT_CORES_ so that code in the parallel package that starts more than two workers fails (R Internals, "Tools"). The usual pattern is to default to one core and to cap at two whenever that variable is set.

Source: R Internals: Tools

The second limit is the Internet. The policy says that a package that uses an Internet resource has to cope with the resource being unavailable or changed, with an informative message and neither a check warning nor a check error, that the use of external resources should be kept to a minimum, and that rate-limit errors such as the HTTP codes 429 and 403 must be avoided because other packages may use the same site. Writing R Extensions adds that installation itself should avoid the Internet where possible. The usual shape is a function that catches the failure, says what happened and returns an empty result, and tests and examples that skip when the resource is missing. The address below is a local port on which nothing listens, so no outside network is involved; the message that readLines() produces is the text R itself prints.

Source: CRAN Repository Policy: Source packages

Writing R Extensions, in its chapter on portable packages, adds a list of things not to do in tests and examples because they pass on one machine and fail on another: do not test how long a command takes, do not test the exact format of messages from R or from other packages (they change and they can be translated, and the message text of the system’s C library or of libcurl changes between versions), do not test for the absence of warnings, compare numbers with a tolerance and only when you have done an error analysis, canonicalise file paths before comparing them, set a seed for anything random, use options(warn = 1) so that warnings are reported when they happen, and test your package in more than one time zone when it handles dates. A package must also run on at least two of the major R platforms; a Windows-only package is considered, though CRAN may not be the right place.

Checking a package should take as little CPU time as possible, because the check farm runs thousands of packages. The policy asks for examples that run for a few seconds at most, for long-running tests and vignette code to be made optional while the tests that are left still exercise every feature, and for tarballs that are small: neither data nor documentation should normally exceed 5 MB, the source tarball should not exceed 10 MB, and large data belongs in a separate data package that is rarely updated. R CMD check --as-cran sets --timings, which lists examples taking more than 5 seconds of CPU or elapsed time, and _R_CHECK_TIMINGS_ to 10 so that timings of 10 seconds or more are reported for installation, examples, tests and vignettes (Writing R Extensions, "Check timing"; R Internals, "Tools").

The Rd macro \donttest is how an example that is correct but slow, or that depends on something the check machine may lack, is kept out of the quick path of a plain check. Since R 4.0.0, R CMD check --as-cran runs the \donttest examples too, so the macro no longer hides code from CRAN: it only keeps it out of example() in a non-interactive session and out of a plain R CMD check. Writing R Extensions says that code inside \donttest has to be correct R code whose packages are declared in DESCRIPTION, and that the code should carry a comment saying why it needs the macro. \dontrun is for code that cannot run at all. The first script shows how the three kinds of example are treated by the Rd tools; the text block under it comes from a throw-away package whose single help page holds a plain example, a \donttest example and a \dontrun example, checked once with a plain R CMD check and once with --as-cran.

Source: R documentation: Rd2ex

Source: R NEWS: Changes in R 4.0.0

The roxygen2 tag @examplesIf writes a conditional example into the Rd file (so that the example runs only when its condition holds, for instance interactive() or the availability of a service), and the test-side counterpart is skip_on_cran() from testthat, which skips a test unless the environment variable NOT_CRAN is set to true; both are explained in Documentation with Rd, roxygen2 and Vignettes and Testing with testthat. The shelf package has one skip_on_cran() test and one snapshot test that is skipped on CRAN, which is why its test summary shows two skips under --as-cran.

The packages a CRAN package needs in Depends, Imports or LinkingTo (its strong dependencies) have to be available from CRAN or from the Bioconductor software repository. A package named in Suggests or Enhances that is on neither has to be located through the Additional_repositories field, a comma-separated list of repository URLs that R CMD check uses to confirm the package can be found, as a source package at least. The field does not install anything; it lets CRAN check that the optional package exists. A suggested package should be used conditionally in examples and tests when it cannot be installed easily on every major platform, which Writing R Extensions recommends doing always: requireNamespace("pkg", quietly = TRUE) before using it. Orphaned CRAN packages must not be strong dependencies. CRAN versions of packages are expected to work with the current CRAN and Bioconductor releases of what they depend on and must not recommend development versions of those or of themselves.

Source: Writing R Extensions: Package Dependencies

That fragment is a placeholder, not a field of the shelf package, which has no strong dependency at all: outside base R it only calls utils::packageVersion(), and utils is attached by default. A package that calls utils:: or stats:: functions should still list them in Imports, which is what usethis::use_package("utils") writes; the check "checking dependencies in R code" in the list further down is the one that reports a package used but not declared. More about declaring dependencies is in Packages, Libraries and Namespaces and Creating Packages.

The policy asks for updates to be submitted responsibly, with respect for the volunteers' time: once a package is established, the interval it considers appropriate is "no more than every 1-2 months". Before submitting a correction, look at the CRAN check page of the package at https://CRAN.R-project.org/web/checks/check_results_NAME.html (replace NAME with the package name) and wait until that page has been fully updated after the previous publication, which can take at least 48 hours. A package that shows an issue on the macOS arm64 flavour should be checked with mac-builder before resubmission. Packages are not normally removed from CRAN, but they are archived when the maintainer asks, when R CMD check gives an ERROR at the release of a new R x.y.0 and the maintainer has not set a firm deadline for an update and kept it, or when warnings and significant notes are left unfixed after the maintainer was asked to update. An archived package keeps its place in the Archive area, and its name stays reserved: the name check of the next section reports a clash with "CRAN archive" as well as with the current index. If an update changes the API of a package that others depend on, the policy expects you to contact their maintainers, suggest changes, give them at least two weeks, ideally more, and mention in the submission which packages are affected and that their maintainers were told.

Keep a NEWS.md (or NEWS) file that says what changed in each version: since R 4.3.0 R CMD check also reports problems it meets when reading that file, CRAN links the news from the package page, and news() reads it back from the installed package, as shown in the section on versions below. Keep README.md for the repository and cran-comments.md for the people who review the submission; the latter is excluded from the tarball with .Rbuildignore. None of the files that a GitHub project accumulates (workflow files, .github, issue templates, pkgdown sources) belongs in the tarball either: they are listed in .Rbuildignore by the usethis functions that create them. The tarball that CRAN receives should contain the package and nothing else, which the listing in the next section shows for shelf.

Source: Writing R Extensions: Building package tarballs

The command is run from the directory that contains the package directory (here ~, so the package is ~/shelf). It installs the package into a temporary library because the vignette has to be built, builds the vignette, drops the files that .Rbuildignore lists and writes shelf_0.1.0.tar.gz. The log below is the real one.

Source: Writing R Extensions: Building package tarballs

What the tarball holds is what CRAN receives. The listing is real: the four patterns of .Rbuildignore keep cran-comments.md, LICENSE.md, .lintr and the data-raw directory out, the built vignette appears under inst/doc with a build/vignette.rds index, and NAMESPACE and the man pages are the files that roxygen2 wrote before the build.

Source: Writing R Extensions: Building package tarballs

The help of R CMD check describes --as-cran as a selection of customizations similar to those CRAN uses. It is a bundle of settings, not a separate program: it sets a number of _R_CHECK_*_ environment variables (the full list with their meaning is in the "Tools" chapter of R Internals), turns on some options such as --timings, and adds checks to the default list. The next lines are the options that matter for a CRAN submission, taken from the help of the same R.

Source: Writing R Extensions: Checking packages

The environment variables that matter most are these. _R_CHECK_CRAN_INCOMING_ turns on the check of whether the package is suitable for publication on CRAN, and _R_CHECK_CRAN_INCOMING_REMOTE_ (default: the value of the first) includes the part of it that needs remote access, the name lookup above and the URL checks. _R_CHECK_FORCE_SUGGESTS_ makes missing suggested packages an error; it defaults to true, but not for the submission checks of CRAN itself, and devtools::check() sets it to false through its argument force_suggests. _R_CHECK_LIMIT_CORES_ caps the cores that code can use, _R_CHECK_TIMINGS_ and --timings report slow steps, _R_CHECK_SYSTEM_CLOCK_ compares the clock of the machine with an external clock as part of "checking for future file timestamps", and _R_CHECK_DONTTEST_EXAMPLES_ can be set to a false value to skip the \donttest examples temporarily while developing. Four changes to the list came with specific releases of R: --as-cran runs \donttest examples from R 4.0.0, validates the HTML version of the manual with HTML Tidy from R 4.2.0, traps leftover browser() calls with _R_CHECK_BROWSER_NONINTERACTIVE_ and checks the KaTeX rendering of mathematics in Rd files from R 4.3.0, and notes bad parts in the URL fields of DESCRIPTION from R 4.5.0.

How much the bundle changes can be measured. The first command below lists the names of the steps of a plain check and of an --as-cran check of the shelf tarball (with the remote part off, so that both finish the same way) and compares them: the plain check has 53 steps and the --as-cran check has 59, and the six that are added are listed.

Source: Writing R Extensions: Checking packages

Source: Writing R Extensions: Checking packages

Lines that start with > are in the --as-cran list only: the CRAN incoming feasibility check, the check for detritus in the temporary directory, the check for future file timestamps, the check for non-standard things in the check directory, the check of the widths of the Rd lines and the check of the registration of S3 methods. The environment is changed as well, and that cannot be seen in the step names. A test file in a throw-away package, tests/probe.R, prints the variables that start with _R_CHECK_ while R CMD check runs it; the first listing is a plain check and the second an --as-cran check, which sets forty-two variables where the plain check sets three, among them _R_CHECK_LIMIT_CORES_, _R_CHECK_TIMINGS_, _R_CHECK_NO_STOP_ON_TEST_ERROR_, _R_CHECK_BROWSER_NONINTERACTIVE_ and _R_CHECK_CODE_USAGE_VIA_NAMESPACES_.

Source: R Internals: Tools

This script is a test file, so it is a fragment: run by Rscript it prints only 0 variables and an empty line, because R CMD check is what sets the variables. Under R CMD check it prints the count, then the variables whose value is not TRUE one per line, then the names of the variables whose value is TRUE, wrapped. The output of a plain R CMD check --no-manual is this:

Source: R Internals: Tools

and the output of R CMD check --as-cran --no-manual is this:

Source: R Internals: Tools

The values are the ones that this R 4.6.1 sets, and CRAN’s own machines add more. The documentation of devtools::check(cran = TRUE), discussed below, says the same about itself: it imitates the settings of CRAN on a best-effort basis, because they keep moving, and is more than a call with --as-cran.

The whole list of what R CMD check --as-cran does for the shelf package, in the order it runs, is shown below, with the remote CRAN-incoming checks switched off through _R_CHECK_CRAN_INCOMING_REMOTE_=false. Every step is OK, the status is OK and the tests step shows that R CMD check ran testthat.R (the skip_on_cran() tests are among the skipped ones).

Source: Writing R Extensions: Checking packages

Grouped by what they protect, the steps are these.

Source: Writing R Extensions: Checking packages

Two of the steps are worth a second look because they decide whether the check finishes in a state CRAN accepts. "Checking R code for possible problems" runs codetools over the code, which finds a variable that is used but never defined, a call to a function that does not exist and arguments that do not match; _R_CHECK_CODETOOLS_PROFILE_="suppressLocalUnused=FALSE" additionally reports local variables that are assigned and never used, which often points at a mistyped name or an assignment in the wrong scope. "Checking re-building of vignette outputs" re-makes the vignettes from their sources in a copy of the package, so a vignette that depends on a file that .Rbuildignore removed fails here and nowhere else. The chapter on style and linting, Style, Linting and Static Analysis, shows codetools::checkUsage() on its own.

"Checking CRAN incoming feasibility" is the step that reproduces what the CRAN machines do first with a submission. Without network access it checks what can be decided locally; with it (_R_CHECK_CRAN_INCOMING_REMOTE_, on by default for --as-cran) it also looks up the package name in the indexes of CRAN and its archive and checks the URLs in the sources. The shelf package passes this step when the remote part is off (the step is reported as OK in the list above) and fails it when it is on. A copy renamed to a free name shows what the step reports for a perfectly good new package. The excerpt is real: the status is a single NOTE.

Source: CRAN: Checklist for submissions

That NOTE, Maintainer: followed by New submission, is the one that cannot be removed and that the template of usethis::use_cran_comments() anticipates: it tells the CRAN team that this is a first submission and that a human has to look at it. Say so in the comments ("This is a new release") and move on. The usual notes of a new submission, with what each means, are these.

Source: R Internals: Tools

The conventions of the text fields are checked mechanically, so they are easy to break and easy to repair. A second copy of the package, renamed shelfbad, was given a lower-case title and a description that starts with "This package"; the real excerpt shows both findings, and tools::toTitleCase() computes the correction.

Source: Writing R Extensions: The DESCRIPTION file

URLs are checked with the equivalent of curl -I -L: the check reports a URL that cannot be fetched, that answers with an error status, or that is redirected permanently (when the redirection is permanent, CRAN wants the final address), and the notes on the CRAN site explain false alarms such as sites that refuse the request type, need cookies or answer 403 and 503 to programs. A placeholder address in inst/CITATION of the shelf package was reported during development as a 404 and was fixed by removing the URL; the CITATION file of shelf has no url today. A third copy, renamed shelfurl, puts the placeholder host example.com back so that the report can be shown; in the container the connection to it failed at the TLS handshake, which gives a different status line from the 404 seen during development, with the same layout of the NOTE.

Source: CRAN: URL checks

Both the 404 and the TLS error mean that the check could not confirm the address, and the cure is the same: use an address that answers, or no address. \url{} markup in Rd files is for always-active URLs only (examples that use localhost use \samp{}). If a site answers 403 or 503 to programs but works in a browser, say so in the submission comments; if a permanent redirect is reported, replace the address by the final one.

R CMD check also builds the PDF manual of the package, which is how a bad Rd file is found, and validates the HTML version of the manual with HTML Tidy (R 4.2.0). The first needs a TeX installation and suitable fonts, the second a recent tidy. The image used for this page has neither, so the commands above use --no-manual, and the same check without that option shows what a missing TeX looks like. The lines are real (a temporary path was removed from the middle of the ERROR text):

Source: Writing R Extensions: Checking packages

On a machine without TeX, --no-manual is the right way to run the checks that matter (devtools::check() passes it by default through manual = FALSE); before submitting, build the manual once on a machine that has TeX, because that is where a bad Rd file shows up. The file shelf-manual.tex reported by the last NOTE is what the failed build left in the check directory.

The R package rcmdcheck (1.4.0) runs R CMD check from R, with its output and its results available as an object: the checks of devtools and of GitHub Actions workflows are built on it. It takes the path of a tarball or a package directory, the arguments for R CMD check and for R CMD build, a check directory and extra environment variables, and returns an object with errors, warnings and notes lists, the package name and version, the exit status and the log. The script below is run from the package root after R CMD build shelf; quiet = TRUE suppresses the live log, and the Duration: line that print() adds (a timing) is dropped from the printed summary.

Source: rcmdcheck package documentation: rcmdcheck

The same call with the remote checks left on (the default for --as-cran) returns the error of the name. This script needs the network, and what it prints depends on the contents of CRAN on the day it runs; the timing that rcmdcheck adds to the first line of the error is left out.

Source: rcmdcheck package documentation: rcmdcheck

devtools::check() is rcmdcheck behind the usual development loop: it builds the package in an independent session, optionally runs devtools::document() first (by default only when the installed roxygen2 matches the version recorded in DESCRIPTION) and checks the result with the settings of CRAN. Its cran = TRUE default asks for the settings CRAN uses, on a best-effort basis; remote = FALSE leaves the remote incoming checks off, incoming follows remote, force_suggests = FALSE keeps the check from failing when suggested packages are absent, run_dont_test = FALSE only matters for R 3.6 and earlier, because in R 4.0 and later \donttest code always runs as part of the CRAN checks, manual = FALSE is --no-manual, and env_vars = c(NOT_CRAN = "true") makes the skip_on_cran() tests run. Pass remote = TRUE for the real incoming check. The result is the same rcmdcheck object, with the same summary.

Source: devtools package documentation: check

The policy and the community guidance agree on the target: no ERRORs, no WARNINGs, and as few NOTEs as possible. In principle a package has to pass without warnings or significant notes to enter the main CRAN area, and a NOTE that cannot be removed is listed and explained in cran-comments.md or in the comment of the submission form.

win-builder (https://win-builder.r-project.org/) is the R project’s service for building and checking source packages on Windows, meant for people who have no Windows machine, and the one the CRAN submission checklist names, saying that the CRAN team uses the same infrastructure for the packages submitted. It builds and checks a source package on Windows with R-devel, R-release or R-oldrelease, each under its own upload directory; the page lists the R version each directory currently holds and the Rtools release it uses. The procedure is to build the tarball with R CMD build, make sure the Maintainer field of DESCRIPTION holds your own email address (the answer is sent there and nowhere else), upload the file by passive FTP in binary mode as an anonymous user to the directory of the R version, or through the upload form, and wait about half an hour for an email that links to a randomly named directory with the binary and the check logs, which is deleted after roughly 72 hours. All CRAN and Bioconductor software packages are already installed on the service; a package that needs another one can be preceded by uploading that one first. The service is a shared machine, so the disclaimer on its page applies: do not upload other people’s packages, and do not expect confidentiality.

devtools wraps the upload so that you do not leave R. The functions check_win_devel(), check_win_release() and check_win_oldrelease() bundle the source package, upload it and make the answer arrive by email at the maintainer’s address (or at email =), which usually takes about 30 minutes; webform = TRUE uses the web form instead of passive FTP. They are a fragment here: running them submits the package to a remote machine.

Source: devtools package documentation: check_win

mac-builder (https://mac.r-project.org/macbuilder/submit.html) is the macOS counterpart, maintained by the people who build the CRAN macOS binaries. You upload a source tarball prepared with R CMD build that lists you as the maintainer, choose the R version (release or development) and optionally add custom dependencies that are not on CRAN (they must not have cycles and must pass their checks). By default the machine has the same setup and packages as the CRAN M1 build machine, so an issue reported on the macOS arm64 flavour of the CRAN check page can be reproduced there. The CRAN policy asks you to check with mac-builder before resubmitting a package that shows issues for macos-arm64. devtools::check_mac_release() and devtools::check_mac_devel() upload the tarball and return the URL with the results. This is a fragment too.

Source: devtools package documentation: check_mac_release

R-hub is the community service for checking a package on many platforms; it is not maintained by CRAN, so its settings can differ from the ones CRAN uses. Since rhub 2.0.0 (2024-04-11) it is a completely new system: R-hub v2 runs R CMD check and similar checks on GitHub Actions, and the functions of the first version (rhub::check(), rhub::check_for_cran(), rhub::validate_email() and friends) are deprecated and defunct. The current release is rhub 2.0.1 (2025-03-06). It is not installed in the image used for this page, so what follows is the documented workflow with its command names, and nothing was run.

The requirements are a GitHub account, a package in a GitHub repository whose origin remote points to it, and a GitHub personal access token stored in the git credential store (for instance with gitcreds::gitcreds_set()). rhub_setup() adds the workflow file .github/workflows/rhub.yaml to the package, which then has to be committed and pushed to the default branch of the repository, rhub_doctor() checks that everything is set up, rhub_platforms() lists the platforms, and rhub_check() starts a check on the platforms you choose, in an interactive menu or through the platforms argument. The platforms are of two kinds: virtual machines on GitHub Actions (linux, macos, macos-arm64, windows) and containers with many more configurations, such as R-devel under several compilers, sanitizers, valgrind, no long doubles, a build without suggested packages, and the donttest container that runs the \donttest examples. The check picks the package up from GitHub, so changes have to be pushed first; the branch argument selects another branch, which needs the workflow file as well; the results are on the Actions tab of the repository and arrive as GitHub notifications, not as an email. Private repositories work and use the free minutes of the GitHub plan. The four calls below are a fragment: they need the repository and the token, and none of them was run.

Source: rhub package documentation: R-hub v2

The workflow file is generated and rarely edited by hand; the first lines of the canonical file in the r-hub/actions repository are shown below as it was on 2026-10-21 (the header comments and the jobs after setup are left out). It starts from workflow_dispatch, which is how rhub_check() triggers it, with a comma-separated list of platforms in the config input, and the rest are jobs built from the r-hub/actions building blocks: setup, checkout, platform-info, setup-deps and run-check, with setup-r for the virtual machines.

Source: R-hub actions: workflows/rhub.yaml

A package that is not on GitHub can still use the shared runners of the R Consortium. rc_new_token() obtains a token for the email address (once per machine and address; rc_list_local_tokens() lists the tokens already present), and rc_submit() submits the package, path or tarball, and the platforms, which must be named explicitly in a non-interactive session; the maintainer’s email address is used unless email = says otherwise. The limits are real: the package and the check output are public in the organization https://github.com/r-hub2, the runners are shared so a build may wait, at least five minutes must pass between submissions, and a GitHub account is needed to read the logs. For anything private, put the package in a private GitHub repository and use rhub_setup() and rhub_check(). The two calls below are a fragment, not run.

Source: rhub package documentation: rc_submit

If the package already lives on GitHub, the quickest way to check it on every push is the standard workflow of the r-lib/actions repository, which usethis::use_github_action("check-standard") copies into .github/workflows/R-CMD-check.yaml (when the name starts with check- the file is saved as R-CMD-check.yaml and a badge is requested for the README), and adds the workflow file to .Rbuildignore. The check-standard workflow runs R CMD check with the latest R release on Linux, macOS and Windows, and with R-devel and the previous release on Linux, which usethis presents as a good baseline for a package that goes to CRAN. It does not change the policy rule that the check must also pass with a development version of R before submission: the devel entry in the matrix does that.

Source: r-lib/actions: examples/check-standard.yaml

The file above is the check-standard example of the v2 branch of r-lib/actions as it was on 2026-10-21 (the header comments are left out); use_github_action() takes the example of the latest published release of the repository, so what it writes can differ in small details. check-r-package runs rcmdcheck with the arguments c("--no-manual", "--as-cran") by default, fails the job on a warning (error-on is "warning" unless you change it), uploads the check results as an artifact when the job fails, and sets _R_CHECK_FORCE_SUGGESTS_ and _R_CHECK_CRAN_INCOMING_ to false when they are not already set in the environment of the job. That last detail matters for this page: with _R_CHECK_CRAN_INCOMING_ off, the incoming feasibility step, and with it the name lookup, is not run by the standard workflow, so a name clash such as the one above is found by R CMD check --as-cran on a developer machine, by R-hub or by CRAN, and not by the default workflow. Its sibling setup-r-dependencies installs the dependencies of the package with pak and caches them.

tools::package_dependencies(reverse = TRUE) computes the reverse dependencies from a matrix shaped like the result of available.packages(): a Package column and the dependency fields Depends, Imports, LinkingTo, Suggests and Enhances. Its which argument takes the field names or the shorthands "strong" (the default), "most" (adds Suggests) and "all", and recursive follows the chain of dependencies. The first script builds that matrix by hand for four imaginary packages that use shelf, so it needs no network and its output never changes. The second one asks the live index about a long-established package and prints only comparisons, because the counts change every day; it needs the network.

Source: R documentation: package_dependencies

Source: R documentation: package_dependencies

The CRAN web page of a package lists its reverse dependencies, and devtools::revdep() returns them as a vector (the first call in a session downloads the metadata of CRAN and Bioconductor); the policy also points to the reverse_dependencies_with_maintainers function on the developer site of R to obtain the maintainers' addresses that have to be told about an API change. The maintainers of affected packages need advance notice, at least two weeks according to the policy.

tools::check_packages_in_dir() is the tool the policy names. It checks every source tarball in a directory, and with a reverse argument it also downloads, installs and checks the reverse dependencies of those packages: reverse = list() takes the defaults (the repositories of getOption("repos"), the strong dependencies and no recursion), and the components repos, which and recursive can be set. The check of each reverse dependency is run against your package, so a failure that is new points at your change. tools::check_packages_in_dir_changes() compares two such runs, one made against the old release and one against the new, and tells you which packages changed status. The script below runs the function for the shelf tarball without reverse, which is all there is to do for a package with no dependents, and lists the directory it creates: Outputs holds the logs, Library the packages installed for the check and shelf.Rcheck the check itself; with reverse, the directories of the reverse dependencies are prefixed rdepends_.

Source: R documentation: check_packages_in_dir

Checking hundreds of packages takes hours and a lot of disk space, which is why most maintainers use a tool that does it incrementally. The package revdepcheck of the r-lib organisation (not installed, not run) runs R CMD check twice for each reverse dependency, once with the CRAN version of your package and once with the local development version, in parallel, and reports the difference, so that failures that already existed do not count against you; it writes its summaries into a revdep directory, and the R Packages book (community material) suggests pasting revdep/cran.md into cran-comments.md. Both of the calls below are fragments.

Source: revdepcheck package documentation

When the reverse checks show a failure that your change causes, you have three possible answers: change your update so that it does not break the user, send the maintainers a patch before submitting, or explain in the comments that the break is intended and that they have been informed. The R Packages book notes that CRAN accepts an update that breaks other packages when the maintainers were given sufficient advance notice.

A package is submitted through the form at https://cran.r-project.org/submit.html, and not by email: the policy is explicit that the submission form is the way in, and that the package itself must never be emailed. The form has three steps (upload, submission, confirmation). In the first you give your name, the email address of the maintainer, the package file (only .tar.gz files, at most 100 MB) and an optional comment; the page reminds you that the tarball has to come from R CMD build, that DESCRIPTION must hold a valid maintainer field of the form NAME <EMAIL>, and that you have to know the rest of the policies. The upload must be a source tarball made by R CMD build and named PACKAGE_VERSION.tar.gz. If someone other than the maintainer submits (a co-author, for instance), say so in the comment: the designated maintainer will have to confirm the submission. If the maintainer’s email address changed, explain it in the comment and, if possible, send a confirmation from the previous address to the submissions mailbox of CRAN as a separate message. If the package needs special treatment (vignettes that can only be rebuilt on the maintainer’s machine or that take very long), say so in the comment too.

CRAN then sends a confirmation email to the maintainer’s address, with a link that must be followed: at that link you are asked to confirm that you have followed the policies and that you want the package submitted. Until you do, the package is not submitted. The email check also confirms that the address in DESCRIPTION works, which is why that address has to be valid and unfiltered. After the confirmation the package enters CRAN’s automatic checks, which the R Packages book (community material) describes as a first round of R CMD check on Windows and Linux, probably with released and development R, with a second email with links to the results usually within hours. A new package is then looked at by a member of the CRAN team; the book adds that the process can be fully automated for an update of a package that is already on CRAN, and that reverse dependency checks follow when the update passes the first round.

Do not submit a package again while the first upload is pending and no reply has arrived, which can take a few days. The policy says you can check that the upload was received by looking at the directory listing at https://CRAN.R-project.org/incoming/. The listing shows, at the time of writing (2026-10-21), the folders archive, inspect, newbies, pending, pretest, publish, recheck, special and waiting, next to folders named after people, each with a last-modified time. CRAN does not document on the policy or submission pages what each folder means, and the names are an implementation detail of the submission system that may change, so use the listing only for what the policy says it is for, to see that a file arrived, and expect the answer by email.

CRAN’s reply is either an acceptance (the usual short message from the CRAN team saying, in community write-ups, that the package is "on its way to CRAN") or a list of things to change. Feedback is normally about something automatic that failed, about the text of DESCRIPTION (the title and the description are real hotspots, according to the R Packages book), about examples and tests that take too long, about the policy items in this page, or about a note that you did not explain. Fix everything in the list, not just the first item.

Resubmission is done in the same way as submission, using the optional comment field of the web form to explain how the feedback was addressed, and not a separate email. Updates to a package that is already on CRAN must have a higher version number, and the policy says that increasing the version at each submission reduces confusion, so it is preferred even when the previous submission was rejected: a new package that was rejected with version 0.1.0 is resubmitted as 0.1.1. The R Packages book adds that this means gaps in released version numbers, which does not matter. Start the comment with a "Resubmission" heading and a list of the changes made, and keep the results of the new checks below it (the next section shows the file).

cran-comments.md is not read by R CMD check and is not part of the package: it is a note to the people who review the submission, kept in the repository, excluded from the tarball with .Rbuildignore and pasted (or sent by devtools::submit_cran()) into the comment field. usethis::use_cran_comments() creates it and adds the .Rbuildignore line, as this script shows in a throw-away project. The template has the results of R CMD check in the format 0 errors | 0 warnings | 1 note, and a bullet for the explanation of the single NOTE that a first submission has.

Source: usethis package documentation: use_cran_comments

The shelf package carries exactly that file:

Source: usethis package documentation: use_cran_comments

The convention is to say what was tested and what the results were: the systems and R versions on which the package was checked (your own machine, win-builder, mac-builder, R-hub or GitHub Actions), the results of R CMD check (the counts, and every NOTE explained), the results of the reverse dependency checks for an update, and the changes made in response to feedback. For a first submission of a package that is not called shelf and that has passed every check on this page, a complete file would look like the first block below; a resubmission adds a section at the top, as in the second one. Both blocks are illustrations, not output of a tool.

Source: usethis package documentation: use_cran_comments

Source: CRAN Repository Policy: Re-submission

For an update, keep the same sections and write what you tested against the previous version: the number of reverse dependencies checked, the packages that fail with the new version and what you did about it (a patch sent to the maintainer, an announcement with the date). If a NOTE cannot be removed, explain it; if a URL check reports a false alarm, say so (CRAN’s URL notes describe the usual causes).

devtools::submit_cran() uploads the tarball through the same web form, filling in your name and email from DESCRIPTION and the comment from cran-comments.md, and then you still have to follow the confirmation link in the email. It is described by devtools as the part of the release process that usethis::use_release_issue() defines. The older devtools::release() was the all-in-one route for years (it asked a list of yes-or-no questions and then submitted), but in devtools 2.5.2 it is deprecated in favour of usethis::use_release_issue(), because its authors no longer use it and cannot promise it follows current practice. use_release_issue() creates a checklist as a GitHub issue, based on the type of release (patch, minor or major), with the steps from the first check until the submission and the steps after acceptance; it can be edited, and you can add your own bullets through an unexported release_bullets() function in the package. The checklist is a plain list of tasks, not an automatic procedure. These are fragments: they need a GitHub repository and, for the second, the web form.

Source: devtools package documentation: submit_cran

A package version is a sequence of at least two, and usually three, non-negative integers separated by single . or - characters, and it is not a decimal number: 0.9 is smaller than 0.75, because 9 is smaller than 75. R parses and compares versions with the class package_version (a numeric_version), which compares component by component. The convention that the R Packages book and usethis follow is major.minor.patch for a released version (a patch for a bug fix without new features, a minor version for compatible new features, a major version for changes that can break users), with a fourth component, .9000, for the development version between releases: usethis::use_dev_version() raises 0.1.0 to 0.1.0.9000 right after a release, so that the development version sorts after the release and before the next one. R accepts - as a separator (1.2-3 is 1.2.3), but the dot form is the recommended one.

Source: R documentation: numeric_version

usethis::use_version() takes the level to raise ("major", "minor", "patch" or "dev"), writes the new Version, adds a heading to NEWS.md if the file exists and, in a repository that uses Git, commits those changes (push = TRUE also pushes). The script runs it in a throw-away project that is not under Git, with the usethis messages switched off: the new project starts at 0.0.0.9000, use_version("minor") makes 0.1.0 and writes the first NEWS.md heading, and use_dev_version() makes 0.1.0.9000 and adds the heading of the development version.

Source: usethis package documentation: use_version

The version of R is part of the contract as well. Depends: R (>= 4.1.0) states the oldest R that can run the package, and it should be there when the code needs something newer: the shelf package uses the backslash lambda \(i), which exists since R 4.1.0, and without the line R CMD build adds the field itself and warns about it. The manual says to drop trailing zeroes (R (>= 4.0) and not R (>= 4.0.0)) and that declaring a dependence on R without a version makes no sense. Do not raise the requirement without a reason: users on older R lose the package. The Imports and Suggests fields take version requirements the same way, testthat (>= 3.0.0), and the policy says that CRAN versions are expected to work with the current CRAN releases of their dependencies.

A function that is going away is first deprecated, then defunct, then removed, with the steps spread over releases so that users and the packages that depend on yours can adapt; this is the practice base R itself follows for its own functions (see help("base-deprecated")). .Deprecated() goes in the body of the old function with the name of the replacement; it signals a warning of class deprecatedWarning with the fields old, new and package. When package is given, the message points to the help page <package>-deprecated that should list the deprecated functions of the package (the help page of Deprecated says so), so the package needs such a help page. .Defunct() does the same with an error of class defunctError. The script shows the messages as R 4.6.1 prints them; the code that the check looks for is _R_CHECK_DEPRECATED_DEFUNCT_, which is on for CRAN submissions and notes the use of recently deprecated or defunct functions in other people’s code.

Source: R documentation: Deprecated

For anything more than a handful of functions, the lifecycle package (not installed here, not run) from the tidyverse team provides a vocabulary and tools: badges (experimental, stable, superseded, deprecated) in the documentation and functions such as lifecycle::deprecate_warn() that warn once every so often and not at every call, and lifecycle::deprecate_stop() for the defunct stage. The R Packages book and the lifecycle site describe the stages. Whatever the tool, give users at least one release with a warning before an error, say in NEWS.md which function replaces which, and use the reverse-dependency check to see who is affected.

A breaking change is not only a removed function. A different return type, a changed default, a warning that becomes an error, a different order of arguments and a changed class all break callers. The policy expects the maintainers of affected packages to be told in advance (at least two weeks, ideally more), expects the submission to name those packages, and warns that a change which causes significant disruption to other packages has to be agreed with the CRAN maintainers well before any publicity. If breaking is inevitable, a new major version, a new function name next to the old one, or a new package for the new design are all better than a silent change.

The two files that readers meet after installation are NEWS.md and inst/CITATION, and both are read back by base R. news(package = "shelf") reads the NEWS.md of the installed package (from R 4.3.0 R CMD check also reports problems it meets reading that file), and citation("shelf") prints the entry that the CITATION file defines, with a BibTeX entry. The CITATION of shelf carries only a title, an author, a year and a note; a url that did not answer would have turned into the NOTE shown earlier. This script needs the installed package, so it loads the build of shelf 0.1.0 installed into a scratch library; loading it prints the startup message first.

Source: R documentation: citation

CRAN re-checks every package continuously, on the flavours listed on the page https://cran.r-project.org/web/checks/ (the three current flavours of R on Debian GNU/Linux, Fedora, macOS and Windows), and each package has its own page at https://CRAN.R-project.org/web/checks/check_results_NAME.html with the status per flavour, the logs and the additional issues (compiler warnings, sanitizers, the donttest run and so on). A maintainer who no longer wants to maintain a package can ask for it to be archived; a package whose check gives an ERROR when a new R x.y.0 is released is archived unless the maintainer has promised and kept a firm date for an update; a package whose maintainer cannot be reached is archived or orphaned. The policy keeps the name: the Archive remains, names stay reserved, and a new maintainer can take over a package with the written agreement of the previous maintainer, or without it for a formally orphaned package. A package whose strong dependency leaves CRAN no longer meets the dependency rule described earlier, which is why the policy treats strong dependencies so strictly.

The checks page is also where a mistake after publication shows. Binary packages for Windows and macOS are built by CRAN, not by the maintainer, by batch jobs, and can take a day or two to appear, longer to reach mirrors. Look at the checks page a few days after each release, and wait until it is fully updated (at least 48 hours) before submitting a fix; the policy asks for exactly that.