rOpenSci Dev Guide 1.0.0: Trilingual and Improved

Read it in: Español.

Read it in: Português.

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 1.0.0, with all changes listed in the changelog.

Now available in Portuguese!

Our guide is now trilingual (English, Spanish, Portuguese)!

Find more about the awesome Portuguese translation project, initiated and powered by our Lusophone members in our blog post.

The translation project and ongoing multilingual maintenance uses our babelquarto package to render multilingual Quarto books and websites. It was recently peer-reviewed by Ella Kaye and João Granja-Correia.

We’re actively working on our babeldown package to create and update translations using the DeepL API.

In the dev guide itself, tools useful for internationalizing packages are mentioned: potools, the experimental rhelpi18n package, selecting a language for a pkgdown website.

Policy Updates

We made some changes to rOpenSci policies and scope:

• New category for rOpenSci internal and peer-review tools.

• Updates to the data retrieval category.

• New explicit rule to only submit one package at a time.

• New requirement to not call the default branch “master”.

• Removed requirement to use a codemeta.json file, now deprecated. Codecontinues to be actively used and developed, but we have found it redundant with other metadata and Codecan generate these data as-needed from DESCRIPTION files.

Editor Guide, Author Guide & Reviewer Guide

The guides that live in our guide. 😸

The whole editor guide was has been restructured to follow the typical flow of submissions, and to better explain how to use the software-review dashboard. We added a section on challenges, and documented how to put the system on vacation (which we generally do over the new year period).

Likewise, we improved the organization and content of the author guide (thanks to Alec Robitaille and Joan Maspons).

In the reviewer guide, we removed the external link to the no-longer maintained Mozilla Review guide (one of our early design sources for peer-review) in favor of explicit enumerated items.

Packaging Best Practices

In the packaging guide (another guide within the guide!), we added guidance for choosing example datasets. Furthermore, we created a section for Packages wrapping external software. The licencing section now explicitly requires acknowledging authors of bundled code. Last but not least, the section about dependencies recommends checking the development status of dependencies.

The whole book now mentions the Air CLI every time it mentions the styler package, as Air can be viewed as styler’s successor.

In the chapter about Package evolution, we added guidance on deprecating data, and explained the drawbacks of renaming a widely-used package.

Testing guidance

We updated our testing guidance with

• a mention of tinytest as an alternative to testthat;
• a note on keeping tests written with testthat self-contained.

Package Documentation

With particular thanks to Alasdair Warwick , we improved the documentation 😉 of our documentation building system, including:

• More details on the technical aspects of docs building for rOpenSci packages;
• Updated math guidance following pkgdown’s update.

We also clarified different strategies to document internal functions, thanks to Claudiu Forgaci.

Metadata & Package Information

We documented more ways to acknowledge contributors:

• in the authorship section of the packaging guide, with Research Organization Registry (ROR) IDs;

• in the chapter about collaboration, the allcontributors R package.

Conclusion

In this post we summarized the changes in the latest version of our book “rOpenSci Packages: Development, Maintenance, and Peer Review”. We are thankful for all contributions that created this release. We are already working on the next version. Don’t hesitate to help us shape it by opening an issue!