rodev: helpers for rOpenSci package authors

We strive for high quality in our suite of packages, in practice via a system of software peer review, and via packaging guidelines that keep growing. There is therefore a risk of increasing the workload of package authors, who already have a lot on their plate. To avoid that, when explaining how to do things in our dev guide, we recommend existing automated tools to authors.

The usethis package implements this important principle: Automate that which can be automated. Your computer was literally born to implement rote-but-fussy stuff for you. https://t.co/OfIUzSBlc7

— Jenny Bryan (@JennyBryan) November 28, 2017

Inspired by the usethis package, we’ve started work on our specific helpers for rOpenSci package authors, rodev. In this note, we’ll present some of the helpers it contains at the moment, and ask for your feedback as an rOpenSci package author.

🔗 Setup and scope

To use rodev, you’ll need to install it from GitHub,

remotes::install_github("ropenscilabs/rodev")

and then, go to the package project you want to test it on. Indeed, rodev works on the active project as defined by usethis.

At the moment, rodev functions are divided into four categories in the pkgdown website reference. In this post, we will not reproduce this classification, but hope you’ll refer to the online reference too!

🔗 Helper for badges

We recommend, and therefore rodev facilitates, the use of repostatus.org badges via use_repostatus_badge(), that calls usethis::use_badge(). At a minimum rodev::use_repostatus_badge("wip") will paste the Markdown code of the badge to your clipboard, but as a reminder from usethis docs “To add badges automatically ensure your badge block starts with a line containing only <!-- badges: start --> and ends with a line containing only <!-- badges: end -->.” To see what statuses are available, you can call rodev::repostatus_badges() that’ll output a data.frame.

Another badge we help authors adding, if their software is under / underwent review, is a peer-review badge, via rodev::use_review_badge() that takes the software review issue number as an argument. E.g. the peer-review badge of the tradestatistics package uses the number 274 because it was reviewed in issue 274.

🔗 One-liner for collaboration friendliness

To foster collaboration-friendliness of repos, we have templates for issues, PRs and CONTRIBUTING.md. Such files need to live in a .github/ folder. Package authors can get our templates by running rodev::use_ro_github() and voilà! the package has a .github/ folder ready to be committed and pushed.

🔗 DESCRIPTION tweaking

We’ve been thinking about asking authors of peer-reviewed packages to add a mention of rOpenSci in the Description of their package DESCRIPTION (this sentence is case-sensitive!). We haven’t added this to our guidance yet, but if/when we do, rodev::add_ro_desc() will add the sentence “This package has been peer-reviewed by rOpenSci (v. {version}).” to the Description, with version automatically replaced by the package current version.

For rOpenSci staff members, rOpenSci is a funder of their work so they can run rodev::add_ro_fnd() to add rOpenSci as an author in DESCRIPTION.

🔗 Conclusion

In this note we briefly presented rodev, a package of helpers for rOpenSci package authors. Its contents, and the behavior of some functions, are expected to change when our guidelines do. Our goal is to add rodev functions in our dev guide. Speaking of our guidance, rodev::read_pkg_guide() will open our online packaging guide in a browser! Also note that we’ve just added a changelog to the package – via usethis::use_news_md(), so evolutions will be tracked!

Do some of rodev helpers sound helpful? Do they work as expected? Do you have some feature requests? Head to rodev issue tracker, we’d be glad to improve the package and ultimately your experience as the author of an rOpenSci package.