rOpenSci Dev Guide 0.5.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 fifth version. To find out what’s new in our dev guide 0.5.0, you can read the changelog, or this blog post for more digested information.

We have resumed activity after a break due to the COVID-19 crisis, but are being gentle with deadlines and timing, giving a lot of grace to all people involved. We’re all doing our best and rOpenSci is trying to be accommodating with schedules during this challenging year.

A curation policy for rOpenSci packages

The most exciting update to our guide is probably the addition of a chapter featuring rOpenSci package curation policy.

This chapter summarizes a proposed curation policy for rOpenSci’s ongoing maintenance of packages developed as part of rOpenSci activities and/or under the rOpenSci GitHub organization. This curation policy aims to support these goals:

• Ensure packages provided by rOpenSci are up-to-date and high quality.

• Provide clarity as to the development status and and review status of any software in rOpenSci repositories.

• Manage maintenance effort for rOpenSci staff, package authors, and volunteer contributors.

• Provide a mechanism to gracefully sunset packages while maintaining peer-review badging.

Noam Ross led the work drafting the policy, and rOpenSci staff are busy cleaning up repositories and associated metadata.

Guidance for package docs

Our requests and tips for package documentation also got some care thanks to suggestions by editor Anna Krystalli, as well as by Mark Padgham and Luke McGuinness.

The documentation section of the packaging guide got structured, for clarity, into a general section where we now underline the need for excellent documentation at submission; a section about roxygen2 use; and a section about URLs in package documentation to explain how to check and correct those before CRAN submissions.

We added a request to better describe the data source of a package in DESCRIPTION, in particular linking to the user-facing website of a data source as opposed to just the API docs.

We have made our advice around setting up redirections from a former pkgdown website to the centrally built one after approval. It is even more crucial now that we encourage setting up a pkgdown website before submission in our author guide: “For any submission or pre-submission inquiry the README of your package should provide enough information about your package (goals, usage, similar packages) for the editors to assess its scope without having to install the package. Even better, set up a pkgdown website for allowing more detailed assessment of functionality online."

Lastly, we added a small section about licences to the packaging guide to make the lists of accepted licenses easier to find; and to link to the useful new chapter about licences in the R packages book by Hadley Wickham and Jenny Bryan.

Updates to our process

The author guide now contains clearer instructions about submissions to the Journal of Open-Source Software (JOSS) to underline that because of the different scope definitions of our system and of JOSS, a publication in JOSS is not guaranteed.

Do not submit it to JOSS consideration until after the rOpenSci review process is over: if your package is deemed in scope by JOSS editors, only the accompanying short paper would be reviewed, (not the software that will have been extended reviewed by rOpenSci by that time). Not all rOpenSci packages will meet the criteria for JOSS.

Regarding our own process, we have split reviewer approval from the review template thanks to a suggestion by Hugo Gruson. Before that, at the end of the process the editor would ask the reviewers to check the box in the review template. This involved a lot of scrolling up in some cases, and did not create notifications since there was sometimes no new comment by the reviewer. Furthermore, this allows us to ask the reviewer to update their estimate of the time they spent reviewing the package in total, including the time responding to the author response.

Guidance for testing

The updates feature two small but useful changes to our testing guidance.

First, we updated our continuous integration guidance by making GitHub Actions come first, as it seems to be gaining popularity. Thanks to Luke McGuinness for initiating the discussion right after having a package reviewed and to Hugo Gruson for sharing his insights. Authors (and reviewers), your fresh perspective on guidance and processes is most welcome!

Next, the chapter about package evolution (your reference if you are thinking about deprecating functions!) now includes guidance about testing deprecated functions. Thanks Scott Chamberlain for the contribution, and thanks to Jindra Lacko and John Blischak for their discussion on RStudio community forum that inspired this addition.

A reference to rOpenSci’s other best guide ????

Our guide featured a quite light chapter about Contributing to rOpenSci. Now that rOpenSci Community Manager Stefanie Butland and Community Assistant Steffi LaZerte have written a whole guide about this topic, the chapter has been transformed into a teaser for it!

???? Proud to release the rOpenSci Community Contributing Guide v0.1.0 by @StefanieButland & @steffilazertehttps://t.co/2xbs4EAiLF#RStats pic.twitter.com/f2a1Xz5Bpq

— rOpenSci (@rOpenSci) August 26, 2020

It is the opportunity for us to congratulate Stefanie and Steffi on the contributing guide, and to encourage you to read it. Here’s to many more versions. ????

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. We are already working on updates for our next version, such as improving guidance for encouraging package citations. Check out the the issue tracker if you’d like to contribute.