rOpenSci accepts packages that meet our guidelines via a streamlined onboarding process. To ensure a consistent style across all of our tools we have developed this concise guide. We strongly recommend that package developers read Hadley Wickham’s concise but thorough book on package development which is available for free online (and print).
We strongly recommend
snake_case over all other styles unless you are porting over a package that is already in wide use.
Avoid function name conflicts with base packages or other popular ones (e.g.
object_verb() naming scheme for functions in your package that take a common data type or interact with a common API.
object refers to the data/API and
verb the primary action. This scheme helps avoid namespace conflicts with packages that may have similar verbs, and makes code readable and easy to auto-complete. For instance, in stringi, functions starting with
stri_ manipulate strings (
stri_sort(), and in googlesheets functions starting with
gs_ are calls to the Google Sheets API (
For functions that manipulate an object/data and return an object/data of the same type, make the object/data the first argument of the function so as to enhance compatibility with the pipe operator (
For more information on how to style your code, name functions, and R scripts inside the
R/ folder, we recommend reading the code chapter in Hadley’s book.
README.md, in the root of the repository. The README should include, from top to bottom (see this example):
* The package name * Badges for continuous integration and test coverage, the badge for rOpenSci peer-review once it has started (see below), and any other badges * Short description of the package * Installation instructions * Brief demonstration usage * If applicable, how the package compares to other similar packages and/or how it relates to other packages * Citation information
where issue_id is the number of the issue in the onboarding repository. For instance, the badge for
rtimicropem review uses the number 126 since it’s the review issue number. The badge will first indicated “under review” and then “peer-reviewed” once your package has been onboarded, and will link to the review issue.
If your package connects to a data source or online service, or wraps other software, consider that your package README may be the first point of entry for users. It should provide enough information for users to understand the nature of the data, service, or software, and provide links to other relevant data and documentation. For instance, a README should not merely read, “Provides access to GooberDB,” but also include, “…, an online repository of Goober sightings in South America. More information about GooberDB, and documentation of database structure and metadata can be found at link.
We recommend not creating
README.md directly, but from a
README.Rmd file (an Rmarkdown file) if you have any demonstration code. The advantage of the
.Rmd file is you can combine text with code that can be easily updated whenever your package is updated.
Extensive examples should be kept for a vignette. If you want to make the vignettes more accessible before installing the package, we suggest creating a website for your package with
devtools::use_readme_rmd() to get a template for a
and to automatically set up a pre-commit hook to ensure that
README.md is always newer than
After a package is accepted, the rOpenSci footer should be added to the bottom of the README file with the following markdown line:
CONDUCT.mdfile in the package root directory, and linking to this file from the
devtools::use_code_of_conduct()will add the Contributor Covenant template to your package.
All exported package functions should be fully documented with examples.
The package should contain top-level documentation for
?foobar-package if there is a naming conflict). Optionally, you can use
?foobar-package for the package level manual file,
@aliases roxygen tag.
The package should contain at least one vignette providing an introduction to the primary package functions and use-cases.
As is the case for a README, top-level documentation or vignettes may be the first point of entry for users. If your package connects to a data source or online service, or wraps other software, it should provide enough information for users to understand the nature of the data, service, or software, and provide links to other relevant data and documentation. For instance, a the vignette intro or documentation should not merely read, “Provides access to GooberDB,” but also include, “…, an online repository of Goober sightings in South America. More information about GooberDB, and documentation of database structure and metadata can be found at link.
We strongly encourage all submissions to use
roxygen2 for documentation.
roxygen2 is an R package that automatically compiles
.Rd files to your
man folder in your package from simple tags written above each function.
More information on using roxygen2 documentation is available on the R packages book.
One key advantage of using
roxygen2 is that your
NAMESPACE will always be automatically generated and up to date.
#' @noRd to internal functions.
NEWS.mdfile in the root of your package. See the sample NEWS file
foobar 0.2.0 (2016-04-01) =========================
DEPRECATED AND DEFUNCT. Under each header list items as needed. For each item give a description of the new feature, improvement, bug fix, or deprecated function/feature. Link to any related GitHub issue like
(#12)will resolve on GitHub in Releases to a link to that issue in the repo.
git tagand pushed up to GitHub, add the news items for that tagged version to a Release on the Releases tab in your GitHub repo with a title like
NEWS, add it to
.Rbuildignore, but not if you use
DESCRIPTION file of a package should list package authors and contributors to a package, using the
[email protected] syntax to indicate their roles (author/creator/contributor etc.) if there is more than one author. See this section of “Writing R Extensions” for details. If you feel that your reviewers have made a substantial contribution to the development of your package, you may list them in the
[email protected] field with a Reviewer contributor type (
"rev"), like so:
person("Bea", "Hernández", role = "rev", comment = "Bea reviewed the package for ropensci, see <https://github.com/ropensci/onboarding/issues/116>"),
Only include reviewers after asking for their consent. Note that ‘rev’ will raise a CRAN NOTE unless the package is built using R v3.5 (r-devel as of 2017-09-21).
Please do not list editors as contributors. Your participation in and contribution to rOpenSci is thanks enough. 🙂
All packages should pass
R CMD check/
devtools::check() on all major platforms.
All packages should have a test suite that covers major functionality of the package.
We recommend using
testthat for writing tests. Strive to write tests as you write each new function. This serves the obvious need to have proper testing for the package, but allows you to think about various ways in which a function can fail, and to defensively code against those. More information.
testthat has a function
skip_on_cran() that you can use to not run tests on CRAN. We recommend using this on all functions that are API calls since they are quite likely to fail on CRAN. These tests will still run on Travis.
Check the extent of your test coverage using the covr package. Including a coverage badge in your package’s README makes it easy for reviewers to see how well-tested your package is. 100% coverage is not required, but editors and reviewers will use coverage reports as a starting point to evaluate that your test suite covers the important functionality of your package.
Even if your use continuous integration, we recommend that you run tests locally prior to submitting your package, as some tests are often skipped. (You may need
Sys.setenv(NOT_CRAN="true") in order to ensure all tests are run.) In addition, we recommend that prior to submitting your package, you use Gabor Csardi’s goodpractice package to check your package for likely sources of errors, and run
find spelling errors in documentation.
We strongly recommend that rOpenSci packages use semantic versioning. A detailed explanation is available on the description chapter.
Git tag each release after every submission to CRAN. [more info]
All rOpenSci packages must use one form of continuous integration. This ensures that all commits, pull requests, and new branches are run through
R CMD check. R is now a natively supported language on Travis-CI, making it easier than ever to do continuous integration. See R Packages and Julia Silge’s Beginner’s Guide to Travis-CI for R for more help. Travis offers continuous integration for Linux and Mac OSX. For continuous integration on Windows, see R + Appveyor. R packages that use compiled code or link
to other libraries or languages should have CI for all platforms.
R packages that use compiled code or link to other libraries or languages should have CI for all platforms.
Continuous integration should also include reporting of test coverage via
a testing service such CodeCov or Coveralls. See the README for the covr package for instructions, as well
Both test status and code coverage should be reported via a badge in your package README.
man-roxygenfolder in the root of your package, and those will be combined into the manual file by the use of
@template <file name>, for example. You can run examples with
Imports instead of
Depends for packages providing functions from other
packages. Make sure to list packages used for testing (
testthat), and documentation (
roxygen2) in your
Suggests section of package dependencies. If you use any packages in your examples sections, make sure to list those, if not already listed elsewhere, in
Enhances section of package dependencies.
For most cases where you must expose functions from dependencies to the user,
you should import and re-export those individual functions rather than listing
them in the
Depends fields. For instance, if functions in your package produce
raster objects, you might re-export only printing and plotting functions from the
xml2for most cases.
warning()to communicate with the user in your functions. Please do not use
cat()unless it’s for a
print.*()method, as these methods of printing messages are harder for the user to suppress.
This is a collection of CRAN gotchas that are worth avoiding at the outset.
Descriptionfield of your
testthat::skip_on_cranin tests to skip things that take a long time but still test them locally and on Travis.
Hadley Wickham’s R Packages is an excellent, readable resource on package development and is available a a free book on the web.
Writing R Extensions is the canonical, usually most up-to-date, reference for creating R packages.