cran-submission

name	cran-submission
description	Complete guide to CRAN submission including policies, pre-submission checks, common issues, and the submission process

CRAN Submission Guide

This skill covers the complete CRAN submission process, from pre-submission preparation through to acceptance and post-release tasks. CRAN (Comprehensive R Archive Network) is the primary repository for R packages and has strict quality requirements.

Rules

1. All exported functions must have @returns and @examples documentation
2. Version number must be greater than the current CRAN version
3. Test on multiple platforms before submission (Windows, macOS, Linux, R-devel)
4. Fix all ERRORs and WARNINGs - CRAN will reject packages with any
5. NOTEs should be explained in cran-comments.md
6. Title case for Title field with no period at the end, under 65 characters
7. Use cph role for copyright holders in Authors@R
8. Check all URLs with urlchecker::url_check()
9. Examples must run without errors (use \donttest{} sparingly)
10. Respond to CRAN within 2 weeks or submission will be archived

Pre-Submission Checklist

Essential Documentation Requirements

Every exported function must have:

#' Function Title
#'
#' @description
#' Detailed description of what the function does.
#'
#' @param x Description of parameter x
#' @param y Description of parameter y
#'
#' @returns A data.frame with columns:
#'   \item{col1}{Description of column 1}
#'   \item{col2}{Description of column 2}
#'
#' @examples
#' # Basic usage
#' result <- my_function(x = 1, y = 2)
#' print(result)
#'
#' # Advanced usage
#' result2 <- my_function(x = 1:10, y = 20)
#'

#' @export
my_function <- function(x, y) {
  # implementation
}

Critical: Use @returns (not @return) for consistency with roxygen2 7.0+.

DESCRIPTION File Requirements

Package: packagename
Title: A Package That Does Amazing Things  # Title case, < 65 chars, no period
Version: 0.1.0  # Must be > current CRAN version
Authors@R: c(
    person("First", "Last", email = "[e-mail]",
           role = c("aut", "cre"),
           comment = c(ORCID = "0000-0000-0000-0000")),
    person("Another", "Author", role = "aut"),
    person("Company Name", role = "cph")  # Copyright holder
    )
Description: Provides tools for amazing analysis. This package implements
    novel algorithms and provides intuitive interfaces. Functions include
    data processing, visualization, and reporting capabilities.
License: MIT + file LICENSE
Encoding: UTF-8
LazyData: true
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.3.0
URL: https://username.github.io/packagename/, https://github.com/username/packagename
BugReports: https://github.com/username/packagename/issues
Suggests:
    testthat (>= 3.0.0),
    knitr,
    rmarkdown
VignetteBuilder: knitr
Config/testthat/edition: 3

Title field rules:

• Title case (capitalize major words)
• No period at end
• Under 65 characters
• Don't start with "A Package for..." (redundant)
• Be specific about what it does

Description field rules:

• One paragraph
• Indent continuation lines with 4 spaces
• Don't start with "This package..."
• Explain what the package does, not just list features
• Mention key algorithms or papers if relevant

Version Numbering

For new submissions:

Version: 0.1.0

For updates (must be > CRAN version):

# If CRAN has 0.1.0, use:
Version: 0.1.1  # Bug fixes
Version: 0.2.0  # New features
Version: 1.0.0  # Major release

Development versions (not for CRAN):

Version: 0.1.0.9000  # Development version after 0.1.0

Multi-Platform Testing

Local Testing

# Standard check
devtools::check()

# Check with remote checking (stricter)
devtools::check(remote = TRUE, manual = TRUE)

# Check with --as-cran flag
devtools::check(args = c('--as-cran'))

Windows Testing

# Check on Windows builder (CRAN's Windows server)
devtools::check_win_devel()   # R-devel
devtools::check_win_release() # R-release
devtools::check_win_oldrelease() # R-oldrelease

You'll receive an email with results in ~30 minutes.

R-hub Testing

# Install rhub
install.packages("rhub")

# Validate email first time
rhub::validate_email()

# Check on multiple platforms
rhub::check_for_cran()

# Specific platforms
rhub::check(platform = "windows-x86_64-devel")
rhub::check(platform = "ubuntu-gcc-release")
rhub::check(platform = "macos-highsierra-release-cran")
rhub::check(platform = "solaris-x86-patched")

# List available platforms
rhub::platforms()

Note: R-hub can be unreliable. GitHub Actions with r-lib/actions is often more reliable.

GitHub Actions

Most reliable multi-platform testing:

# Set up GitHub Actions
usethis::use_github_action("check-standard")

Tests on:

• macOS (release)
• Windows (release)
• Ubuntu (devel, release, oldrel-1)

URL Checking

# Check all URLs in documentation and vignettes
urlchecker::url_check()

# Fix or explain any broken URLs

Common issues:

• DOIs should use https://doi.org/ not http://dx.doi.org/
• Use permanent URLs, not redirects
• Some URLs may be temporarily down (explain in cran-comments.md)

Creating cran-comments.md

Create cran-comments.md in package root:

## Test environments
* local R installation, R 4.4.0
* ubuntu 22.04 (on GitHub Actions), R-devel, R-release, R-oldrel-1
* windows-latest (on GitHub Actions), R-release
* macos-latest (on GitHub Actions), R-release
* win-builder (devel and release)

## R CMD check results

0 errors | 0 warnings | 1 note

* This is a new release.

## Downstream dependencies

There are currently no downstream dependencies for this package.

For Updates

## Test environments
* local R installation, R 4.4.0
* ubuntu 22.04 (on GitHub Actions), R-devel, R-release, R-oldrel-1
* windows-latest (on GitHub Actions), R-release
* macos-latest (on GitHub Actions), R-release

## R CMD check results

0 errors | 0 warnings | 0 notes

## What's changed

This is a minor release that fixes bugs and adds new features:

* Fixed issue with X (#123)
* Added new function Y
* Improved documentation for Z

## Downstream dependencies

I have run R CMD check on downstream dependencies of my package.
All packages passed.

Explaining NOTEs

## R CMD check results

0 errors | 0 warnings | 1 note

* Checking CRAN incoming feasibility ... NOTE

  Maintainer: 'First Last <[e-mail]>'

  New submission

  Possibly misspelled words in DESCRIPTION:
    MCMC (3:49)
    PyMC (9:31)

  These are not misspelled:
  * MCMC is a standard acronym for Markov Chain Monte Carlo
  * PyMC is the name of a Python library

Submission Process

First Submission

# 1. Final checks
devtools::check()
devtools::check_win_devel()
rhub::check_for_cran()
urlchecker::url_check()

# 2. Build the package
devtools::build()

# 3. Submit to CRAN
devtools::submit_cran()

# This will:
# - Build the package
# - Run R CMD check
# - Ask for confirmation
# - Submit to CRAN via web form

Manual Submission

If submit_cran() doesn't work:

1. Build package: devtools::build()
2. Go to https://cran.r-project.org/submit.html
3. Upload .tar.gz file
4. Fill in maintainer email and comments
5. Submit

Confirmation Email

You'll receive an email asking to confirm submission:

• Click the confirmation link within 24 hours
• CRAN will then review your package

CRAN Review Process

Timeline

1. Submission: Upload package
2. Confirmation (immediate): Confirm via email
3. Automated checks (minutes to hours): CRAN runs checks
4. Human review (days to weeks): CRAN volunteer reviews
5. Acceptance or rejection: Email notification

Typical timeline: 1-2 weeks, but can be longer during busy periods.

Common Rejection Reasons

1. ERRORs or WARNINGs in R CMD check
2. Missing documentation (no @returns or @examples)
3. Examples fail or take too long (>5 seconds per example)
4. License issues (incompatible or missing LICENSE file)
5. DESCRIPTION problems (title, description formatting)
6. Failed tests on CRAN's systems
7. Large package size (>5 MB without justification)
8. Writing to user's home directory without permission
9. Internet resources without checks (must fail gracefully if offline)
10. Non-standard file permissions

Common R CMD Check Issues and Fixes

1. Undefined Global Variables

Problem:

checking R code for possible problems ... NOTE
my_function: no visible binding for global variable 'x'
my_function: no visible binding for global variable 'y'

Cause: Using NSE (non-standard evaluation) with dplyr, data.table, etc.

Solution:

# In R/globals.R
utils::globalVariables(c("x", "y", "z"))

# Or use .data pronoun
library(dplyr)
my_function <- function(df) {
  df %>%
    mutate(z = .data$x + .data$y)
}

2. Unused Imports

Problem:

checking dependencies in R code ... NOTE
Namespace in Imports field not imported from: 'package'

Solution: Remove from DESCRIPTION or use somewhere:

#' @importFrom package function

3. Non-ASCII Characters

Problem:

checking R files for non-ASCII characters ... NOTE

Solution: Use Unicode escapes:

# Bad
"Müller"

# Good
"M\u00fcller"

4. Examples Fail

Problem:

checking examples ... ERROR

Solution: Wrap problematic examples:

#' @examples
#' # Basic example (always runs)
#' result <- my_function(x = 1)
#'
#' \donttest{
#' # Slow example (skipped on CRAN)
#' slow_result <- slow_function(x = 1:1000000)
#' }
#'
#' \dontrun{
#' # Requires authentication (never runs)
#' api_result <- call_api(key = "your-key")
#' }

Rules:

• \donttest{}: Runs locally and on CI, skipped on CRAN (for slow examples)
• \dontrun{}: Never runs automatically (for examples needing setup)
• Don't overuse - most examples should run

5. Missing Imports

Problem:

checking dependencies in R code ... WARNING
'::' or ':::' imports not declared from:
  'package'

Solution: Add to DESCRIPTION Imports and use:

#' @importFrom package function

Or declare in NAMESPACE:

importFrom(package, function)

6. LaTeX/PDF Errors

Problem:

checking PDF version of manual ... WARNING

Solution: Fix .Rd formatting issues or use:

# In GitHub Actions
build_args: 'c("--no-manual")'

7. Vignette Build Fails

Problem:

checking re-building of vignette outputs ... WARNING

Solution: Ensure vignettes build:

devtools::build_vignettes()

# Check for missing packages in Suggests

8. File Permissions

Problem:

checking file modes ... NOTE

Solution: Fix permissions:

chmod 644 R/*.R
chmod 644 man/*.Rd
chmod 755 configure

9. Package Size

Problem:

checking installed package size ... NOTE
  installed size is X Mb
  sub-directories of 1Mb or more:
    data   Y Mb