CRAN Extra Checks

Workflow

1. Initial Assessment: Ask user if this is first submission or resubmission
2. Run Standard Checklist: Work through each item systematically (see below)
3. Identify Issues: As you review files, note specific problems
4. Propose Fixes: Suggest specific changes for each issue found
5. Implement Changes: Make edits only when user approves
6. Verify: Confirm all changes are complete

Standard CRAN Preparation Checklist

1. Create NEWS.md: Run usethis::use_news_md() if not already present
2. Create cran-comments.md: Run usethis::use_cran_comments() if not already present
3. Review README:
   • Ensure it includes install instructions that will be valid when the package is accepted to CRAN (usually install.packages("pkgname")).
   • Check that it does not contain relative links. This works on GitHub but will be flagged by CRAN. Use full URLs to package documentation or remove the links.
   • Does the README clearly explain the package purpose and functionality?
   • Important: If README.Rmd exists, edit ONLY README.Rmd (README.md will be overwritten), then run devtools::build_readme() to re-render README.md
4. Proofread DESCRIPTION: Carefully review Title: and Description: fields (see detailed guidance below)
5. Check function documentation: Verify all exported functions have @return and @examples (see detailed guidance below)
6. Verify copyright holder: Check that Authors@R: includes a copyright holder with role [cph]
7. Review bundled file licensing: Check licensing of any included third-party files
8. Run URL checks: Use urlchecker::url_check() and fix any issues

Detailed CRAN Checks

Documentation Requirements

• Required even for functions marked @keywords internal
• Required even if function returns nothing - document as @return None or similar
• Must be present for every exported function

# Missing @return - WILL BE REJECTED
#' Calculate sum
#' @export
my_sum <- function(x, y) {
  x + y
}

# Correct - includes @return
#' Calculate sum
#' @param x First number
#' @param y Second number
#' @return A numeric value
#' @export
my_sum <- function(x, y) {
  x + y
}

# For functions with no return value
#' Print message
#' @param msg Message to print
#' @return None, called for side effects
#' @export
print_msg <- function(msg) {
  cat(msg, "\n")
}

• Required even for functions marked @keywords internal
• Exceptions exist for functions used purely for side effects (e.g., creating directories)
• Examples must be executable

1. Call them with ::: notation: pkg:::my_fun()
2. Use @noRd tag to suppress .Rd file creation

• If showing an error, wrap the call in try() instead
• Consider custom predicates (e.g., googlesheets4::sheets_has_token()) with if () blocks
• Sometimes interactive() can be used as the condition
• Lengthy examples (> 5 sec) can use \donttest{}

# BAD - Will be rejected
#' @examples
#' # my_function(x)  # Don't do this!

#' @examplesIf rlang::is_installed("dplyr")
#' library(dplyr)
#' my_data %>% my_function()

#' @examples
#' if (rlang::is_installed("dplyr")) {
#'   library(dplyr)
#'   my_data %>% my_function()
#' }

DESCRIPTION Title Field

• "A Toolkit for" → Remove
• "Tools for" → Remove
• "for R" → Remove

# BAD
Title: A Toolkit for the Construction of Modeling Packages for R

# GOOD
Title: Construct Modeling Packages

# BAD
Title: Command Argument Parsing for R

# GOOD
Title: Command Argument Parsing

# GOOD
Title: Interface to 'Tiingo' Stock Price API

DESCRIPTION Description Field

• "This package"
• Package name
• "Functions for"

# BAD
Description: This package provides functions for rendering slides.
Description: Functions for rendering slides to different formats.

# GOOD
Description: Render slides to different formats including HTML and PDF.

• What the package does
• Why it may be useful
• Types of problems it helps solve

# BAD (too short)
Description: Render slides to different formats.

# GOOD
Description: Render slides to different formats including HTML and PDF.
    Supports custom themes and progressive disclosure patterns. Integrates
    with 'reveal.js' for interactive presentations. Designed for technical
    presentations and teaching materials.

# BAD
Description: Uses 'case_when()' to process data.

# GOOD
Description: Uses case_when() to process data with 'dplyr'.

# BAD
Description: Implements X-SAMPA processing.

# GOOD
Description: Implements Extended Speech Assessment Methods Phonetic
    Alphabet (X-SAMPA) processing.

# BAD
Description: Handles dates like "the first Monday of December".

# GOOD
Description: Handles dates like the first Monday of December.

URL and Link Validation

# BAD
URL: http://paleobiodb.org/

# GOOD
URL: https://paleobiodb.org/

Found the following (possibly) invalid URLs:
URL: https://h3geo.org/docs/core-library/coordsystems#faceijk-coordinates
     (moved to https://h3geo.org/docs/core-library/coordsystems/)

# Find redirecting URLs
urlchecker::url_check()

# Automatically update to final destinations
urlchecker::url_update()

• CRAN badge URLs (e.g., https://cran.r-project.org/package=pkgname)
• CRAN status badges (e.g., https://www.r-pkg.org/badges/version/pkgname)
• CRAN check results (e.g., https://cranchecks.info/badges/pkgname)
• Package documentation URLs on r-universe or pkgdown sites that deploy after release

Found the following (possibly) invalid file URI:
     URI: CODE_OF_CONDUCT.md
       From: README.md

1. Remove file from .Rbuildignore
2. Use usethis::use_code_of_conduct() which generates sections without relative links

Administrative Requirements

# Required
Authors@R: person("John", "Doe", role = c("aut", "cre", "cph"))

Authors@R: c(
  person("Jane", "Doe", role = c("aut", "cre"),
         email = "jane.doe@posit.co"),
  person("Posit Software, PBC", role = c("cph", "fnd"),
         comment = c(ROR = "03wc8by49"))
)

# If LICENSE shows 2024 but submitting in 2026
# Update: 2024 → 2026

If there are references describing the methods in your package, please add these in the description field...

## Method References

There are no published references describing the methods in this package.
The package implements original functionality for [brief description].

Key Files to Review

• DESCRIPTION: Title, Description, Authors@R, URLs, License year
• R/*.R: Function documentation (@return, @examples, @examplesIf, @noRd)
• README.Rmd (if exists): Edit this file (NOT README.md), then run devtools::build_readme()
• README.md: Review for install instructions, relative links, URLs. Only edit directly if no README.Rmd exists
• cran-comments.md: Preemptive notes for reviewers
• NEWS.md: Version notes for this release
• .Rbuildignore: Files referenced in README

Common Fix Patterns

# Before
Title: A Toolkit for the Construction of Modeling Packages for R

# After
Title: Construct Modeling Packages

# Before
Description: This package provides functions for rendering slides.

# After
Description: Render slides to different formats including HTML and PDF.
    Supports custom themes and progressive disclosure. Integrates with
    'reveal.js' for interactive presentations.

# Before - Missing @return
#' Calculate total
#' @param x Values
#' @export
calc_total <- function(x) sum(x)

# After - Complete documentation
#' Calculate total
#' @param x Numeric values to sum
#' @return A numeric value representing the sum
#' @examples
#' calc_total(1:10)
#' @export
calc_total <- function(x) sum(x)

Useful Tools

• tools::toTitleCase() - Format titles with proper capitalization
• urlchecker::url_check() - Find problematic URLs
• urlchecker::url_update() - Fix redirecting URLs
• usethis::use_news_md() - Create NEWS.md
• usethis::use_cran_comments() - Create cran-comments.md
• devtools::build_readme() - Re-render README.md from README.Rmd
• usethis::use_code_of_conduct() - Add CoC without relative links
• usethis::use_build_ignore() - Ignore files in R package build
• usethis::use_package() - Add a package dependency to DESCRIPTION
• usethis::use_tidy_description() - Tidy up DESCRIPTION formatting

Final Verification Checklist

Files and Structure

• NEWS.md exists and documents changes for this version
• cran-comments.md exists with submission notes
• If README.Rmd exists, it was edited (not README.md) and devtools::build_readme() was run
• README includes valid install instructions (install.packages("pkgname"))
• README has no relative links (all links are full URLs or removed)

DESCRIPTION File

• Title: uses title case
• Title: has no redundant phrases ("A Toolkit for", "Tools for", "for R")
• Title: quotes all software/package names in single quotes
• Title: is under 65 characters
• Description: does NOT start with "This package", package name, or "Functions for"
• Description: is 3-4 sentences explaining purpose and utility
• Description: quotes software/package/API names (including 'R') but NOT function names
• Description: expands all acronyms on first mention
• Description: uses double quotes only for publication titles
• Authors@R: includes copyright holder with [cph] role
• For Posit packages: Includes person("Posit Software, PBC", role = c("cph", "fnd"), comment = c(ROR = "03wc8by49"))
• LICENSE year matches current submission year

Function Documentation

• All exported functions have @return documentation
• All exported functions with meaningful returns have @examples
• No example sections use commented-out code
• Examples avoid \dontrun{} unless truly necessary
• Examples requiring suggested packages use @examplesIf or if guards
• Un-exported functions with examples use ::: notation or @noRd

URLs and Links

• urlchecker::url_check() was run
• All URLs use https protocol (no http links)
• No redirecting URLs (except aspirational CRAN badge URLs)
• Aspirational URLs (CRAN badges, etc.) are left as-is
• No relative links in README that reference .Rbuildignore files

Optional but Recommended

• If concerns about method references, added preemptive note to cran-comments.md
• Reviewed bundled file licensing if including third-party files