rOpenSci Dev Guide 0.4.0: Updates

rOpenSci Software Peer Review’s guidance has been compiled in an online book for more than one year now. We’ve just released its fourth version. To find out what’s new in our dev guide 0.4.0, you can read the changelog, or this blog post for more digested information.

Note that, as indicated in the README of the software review repo, in the interest of reducing load on reviewers and editors as we manage the COVID-19 crisis, rOpenSci is temporarily pausing new submissions for software peer review for 30 days (and possibly longer). Please check back in the software review repository again after 17 April for updates. In this period new submissions will not be handled, nor new reviewers assigned. Reviews and responses to reviews will be handled on a ‘best effort’ basis, but no follow-up reminders will be sent.

Policy and governance changes

Some aspects of the software review process changed.

Policy changes

We’ve added field and laboratory reproducibility tools as a category in scope. Packages that improve reproducibility of real-world workflows through standardization and automation of field and lab protocols, such as sample tracking and tagging, form and data sheet generation, interfacing with laboratory equipment or information systems, and executing experimental designs. (Example: baRcodeR)

Every #rstats package benefits from thorough beer review. Thanks to Jason from @rOpenSci for valuable and refreshing insight!#beerreview #ruODK #emacs #IPA pic.twitter.com/jlpYBC8ARB

— 🐢 Florian (@fistful_of_bass) October 14, 2019

Our reviewer guide now includes guidance for off-thread interactions. We’re glad for community building but don’t want any important information to get lost. If you interact with the package authors and talked about the review outside a review thread (in chats, DMs, in-person, issues in the project repository), please make sure that your review captures and/or links to elements from these conversations that are relevant to the process.

Another change linked to policy is that we clarified our advice related to rOpenSci’s Code of Conduct, thanks to a discussion started by Hugo Gruson and by Carl Boettiger. This Code of Conduct applies automatically to all rOpenSci repositories so maintainers should not include a Code of Conduct to avoid conflict. This way the default CODE_OF_CONDUCT.md of the rOpenSci GitHub organization will be picked up by GitHub in e.g. new issues. We recommend authors to add the following text to the package README:

Please note that this package is released with a [Contributor Code of Conduct](https://ropensci.org/code-of-conduct/). 
By contributing to this project, you agree to abide by its terms.

New ethics guidance

Our polices now feature our expectations regarding “Ethics, Data Privacy and Human Subjects Research”.

Submission form amendments

Our issue template for submissions now:

• explicitly mentions roxygen2. Prospective submitters, note that if you used to write documentation the hard way, you can convert it using rd2roxygen.

• explicitly mentions the packaging guide and guide for authors.

• asks whether the submitted package is intended to go on Bioconductor, similar to what’s asked for CRAN.

Editor guidance

We’ve updated the Editor-in-chief role description to better describe current practice, and to add guidance for when inviting guest editors. tl;dr: editors trust the EiC.

We’ve improved the guidance for the editor in charge of a dev guide release. Quite meta indeed!

How (not) to acknowledge rOpenSci

Packages that have been reviewed can include reviewers as authors and their README features a peer-review badge. We’ve removed the requirement to add the rOpenSci footer, especially as it’s not used on deployed documentation websites that automatically get the same footer as our website. We’ve also removed the suggestion to add a mention of rOpenSci in the Description field of DESCRIPTION.

New security guidance

Our dev guide always has had a chapter called “Package Development Security Best Practices” but it used to be quite empty. We’ve now added more guidance about secrets and package development, including links to useful resources.

For further discussion on the same topic, see this vcr issue about making tests pass in PRs in the absence of necessary secrets.

Package documentation

Documentation

The “Documentation” section of the packaging guide now references the new R6 support in roxygen2 and features slightly changed advice on documentation re-use: we added a con (On the other hand, it means the docs are not readable “in-source” since they’re in another file.); the guidance now mentions @includeRmd and @example; we’ve corrected the location of Rmd fragments.

Documentation website

All rOpenSci packages now have a documentation website that’s centrally built. We’ve added some elements helping package maintainers:

• improved guidance regarding the replacement of “older” pkgdown website links and source, thanks Carl Boettiger.

• add package logo guidance. To use your package logo in the pkgdown homepage, refer to usethis::use_logo(). If your package doesn’t have any logo, the rOpenSci docs builder will use rOpenSci logo instead.

• If your package vignettes need credentials (API keys, tokens, etc.) to knit, you might want to precompute them since credentials cannot be used on the docs server.

• How to use of MathJax with rotemplate, thanks to Hugo Gruson.

• A mention that all rOpenSci docs websites automatically have search enabled using Algolia. See e.g. pdftools website.

Misc

CRAN gotchas

We’ve added two CRAN gotchas. It’s especially nice that those were contributed by package authors to lessen the probability of other authors’ missing details of the policies. The gotchas are:

• In both the Title and Description fields, the names of packages or other external software must be quoted using single quotes (e.g., ‘Rcpp’ Integration for the ‘Armadillo’ Templated Linear Algebra Library). Thanks Aaron Wolen.

• Do not put ‘in R’ or ‘with R’ in your title as this is obvious from packages hosted on CRAN. If you would like this information to be displayed on your website nonetheless, check the pkgdown documentation to learn how to override this. Thanks Hugo Gruson.

Forum guidance

We’ve clarified how to use rOpenSci forum in the collaboration guide and in the chapter about marketing your package.

Package dependencies

We’ve added advice on specifying dependency minimum versions and on Bioconductor dependencies in the section about package dependencies.

Meta: changes in deployment

GitHub actions

We’ve started using GitHub Actions instead of Travis for deployment.¹ We’ve got three workflows:

• whenever there’s a push to master, the book is built in a _book folder whose content is then pushed to the gh-pages branch that’s the source for our production book.

• whenever there’s a push to dev, the book is built in a _book folder whose content is then pushed to the dev-site branch that’s the source for our dev book.

• whenever there’s a commit in a PR from the same repo i.e. not a fork, the book is built, deployed to Netlify, and the details page of a PR check run allows to find the preview URL. Getting the preview for any PR was the main motivation for our exploring a different deploy method.

If you want to know more about GitHub Actions for R, we recommend Jim Hester’s RStudio conf talk and Emil Hvitfeldt’s thorough walkthrough “Deploy your bookdown project to Netlify with Github Actions”. You can also explore our (probably improvable) workflows.

URL checking

Our script checking URLs now uses commonmark instead of regular expressions. If you’re interesting in programmatic URL cleaning, you can also read the recent rOpenSci tech note about cleaning a website URLs with R.

Conclusion

In this post we summarized the changes incorporated into our book “rOpenSci Packages: Development, Maintenance, and Peer Review” over the last six months. We are grateful for all contributions that made this release possible. Although our release frequency has now slowed down, we are already working on updates for our next version, such as how to permit multiple documentation websites for development vs release versions of a package. Check out the the issue tracker if you’d like to contribute.