June 9, 2022 From rOpenSci (https://deploy-preview-488--ropensci.netlify.app/blog/2022/06/09/devguide-0.8.0/). Except where otherwise noted, content on this site is licensed under the CC-BY license.
rOpenSci Software Peer Review’s guidance is gathered in an online book that keeps improving! This blog post summarises what’s new in our Dev Guide 0.8.0, with all changes listed in the changelog.
After many years of fabulous contributions to the rOpenSci community, Stefanie Butland left the role of community manager at the start of 2022. The Dev Guide included several references to Stefanie, particularly regarding preparing blog posts, as well as preparing Dev Guide releases. Her name has been removed and replaced with a generic “Community Manager” title.
This version of the Dev Guide reflects the recent expansion of our peer-review system to include statistical software. The Aims and Scope section now explains that statistical software is also within scope, and links directly to the Statistical Software Dev Guide.
One of the largest changes in the current release is in the Guide for Authors chapter. This used to be a largely unstructured collection of dot points reflecting our evolving “best practices”. These points were collated and refined as our peer review system evolved over the years. The updated Guide for Authors chapter provides a more structured reference, divided into the four main sections of:
These changes should both make the chapter more informative for people planning to submit packages for review, and also clarify what authors can expect from our peer review process. Additional changes include informing authors of packages under review that they can now directly call @ropensci-review-bot check package at any time during review to trigger an automated package report.
We also now have explicit advice under Planning a Submission to ensure availability during the review process, and to consider the valuable time volunteered by package reviewers. In The Review Process, we also advise authors to immediately inform us if they are no longer able to respond to reviewers. These improvements to the Authors Guide should hopefully improve coordinated time management of all those involved in software reviews.
The Editors' Guide Chapter now includes an additional section on “Answering Reviewers' Questions”, with links to a few previous reviews in which editors have worked with reviewers and package authors to implement major package changes prior to ultimate acceptance.
Our automation processes continue to ease the burden on all those involved in our software peer review system. This version of the Dev Guide can happily jettison an entire “approval comment template” that reviewers used to have to copy-and-paste into an issue. That template is now automatically inserted by the @ropensci-review-bot as soon as a submission is approved. As described above, authors can now also call check package directly in a GitHub review thread.
Our Continuous Integration Best Practices chapter now states that all packages are checked on submission by our own internal pkgcheck system, and that this system is also available as a GitHub action which authors are encouraged to use prior to submission. That section now also includes a general description of GitHub actions.
While not exactly an automation enhancement, our review template now explicitly states that reviewers can download a local copy, and complete a review either as an Rmarkdown (.Rmd) or plain markdown (.md) document, and simply copy-and-paste into the GitHub issue to complete the review. We are indebted to Hugo Gruson for that clarificiation.
In addition to the automation advances described above, this release of the Dev Guide has also been eased through automation, notably through collecting several scripts and helper functions in a new R package, devguider. One function, prerelease_checklist(), collects all current issues on the Dev Guide GitHub repository that are associated with the upcoming release, adds then to our pre-release checklist, and opens a new GitHub issue with all of those items as a checklist used to guide the next release. This checklist also contains explicit instructions on using other functions from the devguider package.
contributing.md files
Having a contributing file is compulsory for rOpenSci packages, and is automatically checked by our automated package checks. We’ve updated our recommendations for CONTRIBUTING.md files to suggest a number of explicit approaches, including the one-line usethis::use_tidy_contributing() function, and links to two more extensive examples of contributing guides. We now also recommend the inclusion of a lifecycle statement in package contributing guides, to give contributors an understanding of the likely future development of a package.
In response to an idea from Klaus Vigo, the section of package authorship now has an additional section describing how to acknowledge additional authors of external code included in a package.
Standard rOpenSci practice is to acknowledge package reviewers in your DESCRIPTION file by including their names with a role = "rev" identifier (subject to their approval). This used to raise notes in CRAN package checks on older versions of R. That is thankfully no longer the case, and we are happy to have finally been able to remove that statement. Everybody can now simply insert role = "rev" to acknowledge all reviewers, and all CRAN systems will happily recognise those statements.
We have updated our guidance on package evolution to include a new section on package archiving. This section reflects our updated policies that archived packages should move README.md to an alternative location, and reduce the main README.md to a minimal form explaining only that the package has been archived, and linking to the former README.md contents.
Our Package Security Best Practices now recommend the use of two-factor authentication (2FA) for GitHub, and clarify that 2FA is mandatory for all rOpenSci organization members and outside collaborators.
The Citation guidelines now suggest using the cffr package to create a CITATION.cff file.
The Further Guidance on Package Development now includes a section on useful blogs.
The appendix on redirecting package documentation has been updated thanks to Peter Desmet (#387).
The Testing section of the Packaging Guide chapter has an expanded list of recommended packages, particularly those for testing and mocking responses from web resources. That section now also suggests reading the blog post, "Why good developers write bad unit tests", by Michael Lynch.
The Recommanded Scaffolding section of the Packaging Guide chapter now includes explicit recommendation of spatial packages, and details of (soon-to-be) obsolete spatial packages.
The section in that chapter on roxygen2 use in documentation also describes the @seealso and @family tags for grouping functions in package documentation sites.
The section in the Collaboration Guide Chapter on “Working with collaborators” has been streamlined, with additional links on giving and receiving code reviews.
In this post we summarized the changes incorporated into our book “rOpenSci Packages: Development, Maintenance, and Peer Review” over the last months. We are thankful for all contributions that shaped this release. We are already working on the next version, including further improvements such as guidance on packages which wrap other software, and recommendations for further automation.
