Your package is already on GitHub

Since your package is already on GitHub, any R user can install it with

remotes::install_github("USER/REPO")

If you want to tag it as a release, make sure there’s a NEWS.md file then run

usethis::use_version() # set the release version number

Check the NEWS.md file is up-to-date (use_version() will modify it) then

usethis::use_github_release()

This will bundle the source code as a zip and a tar.gz and make them available from the Releases section of the repo homepage.

R-Universe

With R-Universe, you can create a personal, CRAN-like repository.

You’re in control of what’s published in your R-Universe!

It is a good way to allow users to easily install packages without going through the rigour of the CRAN submission process.

Useful resources:

• Search the whole R-universe: https://r-universe.dev/search/
• About the R-universe: https://ropensci.org/r-universe/
• R-universe help-page: https://github.com/r-universe-org/help

Installing a package from an R-universe

Binaries are built for Windows and MacOS, which a user can install using install.packages(), e.g.

# Install 'warwickplots' from the 'warwick-stats-resources' universe
install.packages('warwickplots', repos = c(
  WSR = 'https://warwick-stats-resources.r-universe.dev',
  CRAN = 'https://cloud.r-project.org')
)

options(repos = c(
  WSR = 'https://warwick-stats-resources.r-universe.dev',
  CRAN = 'https://cloud.r-project.org')
)
install.packages("warwickplots")

Create your R-universe

Follow this rOpenSci guide: How to create your personal CRAN-like repository on R-universe.

What happens next

• After a few minutes, your source universe will appear on: https://github.com/r-universe/<username>

• The universe automatically starts building the packages from your registry. Once finished, they will appear on https://<username>.r-universe.dev

• The universe automatically syncs and builds your package git repos once per hour.

• If you encounter any issues, the actions tab in your source universe may show what is going on, for example: https://github.com/r-universe/maelle/actions

Why publish on CRAN?

• Sign of quality

  • Code is ready to be used (not a beta version)
  • Basic standards: documented code, running examples, etc
  • Works with current version of R and other packages
  • Commitment of maintainer

• Discoverability

• Ease of installation

• Bioconductor, rOpenSci: even higher standards, code review

It’s an involved process

• Read the official Checklist for CRAN Submissions to check requirements beyond the automated checks.

• Read the community-created Prepare for CRAN checklist.

• Useful functions for additional checks:

  • goodpractice::gp()
  • spelling::spell_check_package()

usethis::use_release_issue()

This function will first ask you to select the release version (major, minor, patch) then create and open a to-do list as an issue in the package GitHub repo.

For a first submission, there are around 22 tasks to complete, split into sections, to follow (more-or-less) in order:

• First release (one-time only)
• Prepare for release
• Submit to CRAN
• Wait for CRAN (things to do after package has been accepted)

For more details on each, see the Releasing to CRAN chapter of the R Packages book.

Run “as CRAN” checks

CRAN policies state that you must run R CMD check --as-cran on the tarball to be uploaded with the current version of R-devel.

First make sure the package passes check locally:

devtools::check()

Then allow some extra checks:

devtools::check(remote = TRUE, manual = TRUE)

Then send to CRAN’s win-builder to check on R-devel

devtools::check_win_devel()

Also check on Mac (M1)

devtools::check_mac_release()

R-hub v2

• A new (since April 2024) check system.
• Works best if the package is on GitHub
• Works with GitHub Actions

# run once
install.packages("rhub") 
rhub::rhub_setup() # guides through set-up process
rhub::rhub_doctor() # checks the set-up

# run the checks
rhub::rhub_check()

See the r-hub blog post for more details

cran-comments.md

Write submission notes, generating the cran-comments.md file with

usethis::use_cran_comments()

 ## Test environments
 * local OS X install (R-release)
 * win-builder (R-release, R-devel) 

 ## R CMD check results

 0 errors | 0 warnings | 1 note

 * This is a new release.

There’s always one note for a new submission.

Submit to CRAN

devtools::release()

This asks you questions which you should carefully read and answer.

If your submission fails

Do not despair! It happens to everyone, even R-core members.

If it’s from the CRAN robot, just fix the problem & resubmit.

If it’s from a human, do not respond to the email and do not argue. Instead update cran-comments.md & resubmit.

For resubmission

 This is a resubmission. Compared to the last submission, I
 have:

 * First change.
 * Second change.
 * Third change.

 --

 ## Test environments
 * local OS X install, R 3.2.2
 * win-builder (devel and release)

 ## R CMD check results
 ...

Subsequent submissions to CRAN

Proceed as before. If you have reverse dependencies you need to also run R CMD check on them, and notify CRAN if you have deliberately broken them.

Fortunately the revdepcheck package makes this fairly easy

remotes::install_github("r-lib/revdepcheck")
usethis::use_revdep()

revdepcheck::revdep_check()
revdepcheck::revdep_report_cran() # get intermediate report for cran 

Promoting your package

• Some promotion will/may be done for you: CRANberries, search engines (vignette/pkgdown site)
• Some channels are obvious: personal website, blog, Mastodon (#RStats)
• Publicize your new package via R Weekly https://rweekly.org/
  • Add to the weekly news blog, see CONTRIBUTING, and example pull requests new package, new version.
• Would your package fit in a CRAN Task View? https://cran.r-project.org/web/views/
  • Check GitHub organization for how to propose addition.

Talks

• Meetups: Warwick RUG, Coventry R-Ladies (or your local groups)
• Conferences https://jumpingrivers.github.io/meetingsR/events.html
  • General: useR!, posit::conf, satRdays
  • Specific: R/Finance, BioC, Psychoco
  • Non R-specific: Royal Statistical Society (RSS), ???
• Conferences provide greater exposure, particular to people working in relevant field(s).
• Don’t forget to share your slides! (Conference/personal website, LinkedIn, RPubs, Slideshare)

Paper

usethis::use_upkeep_issue()

This is a new function in usethis. Like usethis::use_release_issue(), it opens a GitHub issue with an (opinionated) to-do list of tasks that should be ticked off for your package (at least) once a year.

The tidyverse team think of this like ‘spring cleaning’ for packages.

Blog post: Package spring cleaning

Interacting with users

• Bug reports/help requests
  • Can show where documentation/tests need improving
  • Help you find out who’s using your package and what for
  • Can give ideas for new features
  • Can lead to collaborations
• Avoid using email, so that other people can benefit
  • GitHub issues
  • Stackoverflow questions

Interacting with developers

Consider the longer-term

• Work on new features and bug fixes for the next release
• Buddy-up
  • Review each other’s code
  • Co-author each other’s packages
• Take advantage of events e.g. Hacktoberfest, Closember
• Start work on your next package!

We value your feedback

Please take a few minutes to complete this anonymous feedback form

Thanks!

References

Wickham, H and Bryan, J, R Packages (2nd edn, in progress), https://r-pkgs.org.

R Core Team, Writing R Extensions, https://cran.r-project.org/doc/manuals/r-release/R-exts.html

rOpenSci Packages: Development, Maintenance, and Peer Review https://devguide.ropensci.org/index.html

rOpenSci Statistical Software Peer Review (especially Chapter 3: Guide for Authors) https://stats-devguide.ropensci.org/pkgdev.html

License

Licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (CC BY-NC-SA 4.0).