diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml index c0074be0e..5fdfae7f3 100644 --- a/.github/workflows/pr.yml +++ b/.github/workflows/pr.yml @@ -4,12 +4,12 @@ name: PR-workflow jobs: bookdown: - name: Render Book - runs-on: macOS-latest env: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }} NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }} + name: Render Book + runs-on: macOS-latest if: github.repository == 'ropensci/dev_guide' steps: - name: Is this a fork diff --git a/.zenodo.json b/.zenodo.json index fcd08de27..3188022a9 100644 --- a/.zenodo.json +++ b/.zenodo.json @@ -66,7 +66,8 @@ }, { "name": "Riederer, Emily", - "affiliation": "Capital One" + "affiliation": "Capital One", + "orcid": "0000-0002-1788-7934" }, { "name": "Sparks, Adam", diff --git a/DESCRIPTION b/DESCRIPTION index ff9910c52..de2d76e5e 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,8 +1,8 @@ -Package: placeholder +Package: rOpenSci_dev_guide Type: Website Title: rOpenSci Packages: Development, Maintenance, and Peer Review Description: rOpenSci Packages: Development, Maintenance, and Peer Review -Version: 0.0.1 +Version: 0.8.0 Imports: airtabler, htmltools, @@ -21,3 +21,4 @@ Remotes: rstudio/bookdown, r-lib/downlit, r-lib/rlang +URL: https://github.com/ropensci/dev_guide diff --git a/appendix.Rmd b/appendix.Rmd index 5dc22a7a9..b72ace44a 100644 --- a/appendix.Rmd +++ b/appendix.Rmd @@ -2,13 +2,75 @@ # NEWS {#booknews} +## 0.8.0 + +- 2022-06-03, Remove former references to now-archived "rodev" package + +- 2022-05-30, Advise that reviewers can also directly call `@ropensci-review-bot check package` + +- 2022-05-27, Add Mark Padgham to list of authors + +- 2022-05-27, Add `devguider::prerelease_checklist` item to pre-release template (#463) + +- 2022-05-13, Align version number in DESCRIPTION file with actual version (#443) + +- 2022-05-13, Update guidelines for CONTRIBUTING.md (#366, #462) + +- 2022-05-09, Add section on authorship of included code, thanks to `@KlausVigo` (#388). + +- 2022-05-09, Remove mention of 'rev' role requiring R v3.5 + +- 2022-05-05, Move all scripts from local `inst` directory to `ropensci-org/devguider` pkg. + +- 2022-05-03, Update package archiving guidance to reduce README to minimal form. + +- 2022-04-29, Advise that authors can directly call `@ropensci-review-bot check package`. + +- 2022-04-29, Describe `pkgcheck-action` in CI section. + +- 2022-04-29, Update scope in policies section to include statistical software. + +- 2022-04-29, Add `prelease.R` script to open pre-release GitHub issue & ref in appendix. + +- 2022-04-26, Add GitHub 2FA recommendation to package security. + +- 2022-03-29, Remove references to Stef Butland, former community manager. + +- 2022-03-28, Add comments on submission planning about time commitment. + +- 2022-03-24, Remove approval comment template (coz it's automatically generated by the bot now). + +- 2022-03-21, rephrase CITATION guidance to make it less strict. Also mentions CITATION.cff and the cffr package. + +- 2022-03-08, add links to blogs related to package development (#389). + +- 2022-02-17, update redirect instructions (`@peterdesmet`, #387). + +- 2022-02-14, link to Michael Lynch's post Why Good Developers Write Bad Unit Tests. + +- 2022-02-14, mention more packages for testing like dittodb, vcr, httptest, httptest2, webfakes. + +- 2022-01-10, make review templates R Markdown files (`@Bisaloo`, #340). + +- 2022-01-14, update guidance on CI services (#377) + +- 2022-01-11, update guidance around branches, with resources suggested by `@ha0ye` and `@statnmap`. + +- 2022-01-10, divide author's guide into sub-sections, and add extra info including `pkgcheck`. + +* 2021-11-30, adds links to examples of reviews, especially tough but constructive ones (with help from `@noamross`, `@mpadge`, #363). + +* 2021-11-19, add recommended spatial packages to scaffolding section (software-review-meta#47) + +* 2021-11-18, update advice on grouping functions for pkgdown output (#361) + ## 0.7.0 * 2021-11-04, add mentions of stat software review to software review intro and to the first book page (#342). * 2021-11-04, mention pkgcheck in the author guide (@mpadge, #343). -* 2021-11-04, add editors' responsabilities including Editor etiquette for commenting on packages on which you aren't handling/reviewing (@jhollist, #354). +* 2021-11-04, add editors' responsibilities including Editor etiquette for commenting on packages on which you aren't handling/reviewing (@jhollist, #354). * 2021-11-04, give precise examples of tools for installation instructions (remotes, pak, R-universe). @@ -291,34 +353,6 @@ Editors may make use of the e-mail template below in recruiting reviewers. ``` -# Approval comment template {#approvaltemplate} - -````markdown -```{r, eval = !knitr::is_latex_output(), results="asis", echo=FALSE, comment = ""} -withr::with_tempfile("tf", { -download.file( - "https://raw.githubusercontent.com/ropensci/software-review/master/.buffy/templates/approved.md", - tf - ) - lines <- readLines(tf) -cat(lines[2:(length(lines) - 1)], sep = "\n") -} -) - -``` -```` - -```{r, eval = knitr::is_latex_output(), echo=FALSE, comment = "", results='asis'} -withr::with_tempfile("tf", { -download.file( - "https://raw.githubusercontent.com/ropensci/software-review/master/.buffy/templates/approved.md", - tf - ) - lines <- readLines(tf) -cat(lines[2:(length(lines) - 1)], sep = "\n\n") -} -) -``` # Reviewer approval comment template {#approval2template} @@ -343,6 +377,10 @@ cat(lines[2:(length(lines) - 1)], sep = "\n\n") # Book release guidance {#bookreleaseissue} +Editors preparing for a release can run the `prelease.R` script in the `inst` directory of this repository to automatically open a GitHub issue with checkpoints for all current issues assigned to the upcoming release milestone, along with the following checklist. +Before running the script, please manually check the assignment of issues to the milestone. +This should be run one month prior to planned release. + ```markdown ```{r, eval = !knitr::is_latex_output(), child="templates/book-release.md"} @@ -357,15 +395,12 @@ cat(lines[2:(length(lines) - 1)], sep = "\n\n") ## Non GitHub pages site (e.g. Netlify) -Replace the content of the current website with +Replace the content of the current website with a `index.html` and `404.html` files both containing: ```html - - + ``` @@ -374,7 +409,6 @@ Replace the content of the current website with You can setup the redirect from your main user gh-pages repository: - - create a new repository (if you don't have one yet): `https://github.com//.github.io` - - In this repository create a directory `` containing the file `index.html` that redirects to the new location (see previous subsection) - - Test that https://.github.io//index.html now redirects - - Optional: you could even create a `404.html` file in your `.github.io` repo to redirect arbitrary pages. + - create a new repository (if you don't have one yet): `https://github.com//.github.io`. + - In this repository create a directory `` containing 2 files: a `index.html` and `404.html` file, which both redirect to the new location (see previous subsection). + - Test that `https://.github.io//index.html` now redirects. diff --git a/index.Rmd b/index.Rmd index 9ecb6a9bd..9f5aa23ba 100644 --- a/index.Rmd +++ b/index.Rmd @@ -1,6 +1,6 @@ --- title: "rOpenSci Packages: Development, Maintenance, and Peer Review" -author: "rOpenSci software review editorial team (current and alumni): Brooke Anderson, Scott Chamberlain, Laura DeCicco, Julia Gustavsen, Jeff Hollister, Anna Krystalli, Mauro Lepore, Lincoln Mullen, Karthik Ram, Emily Riederer, Noam Ross, Maëlle Salmon, Adam Sparks, Melina Vidoni" +author: "rOpenSci software review editorial team (current and alumni): Brooke Anderson, Scott Chamberlain, Laura DeCicco, Julia Gustavsen, Jeff Hollister, Anna Krystalli, Mauro Lepore, Lincoln Mullen, Mark Padgham, Karthik Ram, Emily Riederer, Noam Ross, Maëlle Salmon, Adam Sparks, Melina Vidoni" date: "`r Sys.Date()`" site: bookdown::bookdown_site documentclass: book @@ -52,7 +52,7 @@ The [second section](#softwarereviewintro) is dedicated to rOpenSci's software p The [third and last section](#collaboration) features our best practice for nurturing your package once it has been onboarded: how to collaborate with other developers, how to document releases, how to promote your package and how to leverage GitHub as a development platform. The third section also features a [chapter for anyone wishing to start contributing to rOpenSci packages](#contributingguide). -We hope that you'll find the guide useful and clear, and welcome your suggestions in the [issue tracker of the book](https://github.com/ropenscilabs/dev_guide/issues). Happy R packaging! +We hope that you'll find the guide useful and clear, and welcome your suggestions in the [issue tracker of the book](https://github.com/ropensci/dev_guide/issues). Happy R packaging! The rOpenSci editorial team. @@ -69,5 +69,7 @@ done <- file.remove("dev_citation_BibTeX.bib") _If you want to contribute to this book (suggestions, corrections) please refer to [the GitHub repository](https://github.com/ropensci/dev_guide) in particular [the contributing guidelines](https://github.com/ropensci/dev_guide#contributing). Thanks!_ -_We are thankful for all authors, reviewers and guest editors for helping us improve the system and this guide over the years. Thanks also to the following persons who made contributions to this guide and its previous incarnations: [Katrin Leinweber](https://github.com/katrinleinweber), [John Baumgartner](https://github.com/johnbaums), [François Michonneau](https://github.com/fmichonneau), [Christophe Dervieux](https://github.com/cderv), [Lorenzo Busetto](https://github.com/lbusett), [Ben Marwick](https://github.com/benmarwick), [Nicholas Horton](https://github.com/nicholasjhorton), [Chris Kennedy](https://github.com/ck37), [Mark Padgham](https://github.com/mpadge), [Jeroen Ooms](https://github.com/jeroen), [Sean Hughes](https://github.com/seaaan), [Jan Gorecki](https://github.com/jangorecki), [Joseph Stachelek](https://github.com/jsta), [Dean Attali](https://github.com/daattali), [Julia Gustavsen](https://github.com/jooolia), [Nicholas Tierney](https://github.com/njtierney), [Rich FitzJohn](https://github.com/richfitz), [Tiffany Timbers](https://github.com/ttimbers), [Hilmar Lapp](https://github.com/hlapp), [Miles McBain](https://github.com/milesmcbain), [Bryce Mecum](https://github.com/amoeba), [Jonathan Carroll](https://github.com/jonocarroll/), [Carl Boettiger](https://github.com/cboettig/), [Florian Privé](https://github.com/privefl), [Stefanie Butland](https://github.com/stefaniebutland), [Daniel Possenriede](https://github.com/dpprdan/), [Hadley Wickham](https://github.com/hadley/), [Hugo Gruson](https://github.com/bisaloo/), [Mauro Lepore](https://github.com/maurolepore/), [Matthew Fidler](https://github.com/mattfidler), [Luke McGuinness](https://github.com/mcguinlu), [Aaron Wolen](https://github.com/aaronwolen), [Indrajeet Patil](https://github.com/IndrajeetPatil), [Kevin Wright](https://github.com/kwstat), [Will Landau](https://github.com/wlandau), [Hugo Gruson](https://github.com/Bisaloo). Please tell us if we forgot to acknowledge your contribution!_ +_We are thankful for all authors, reviewers and guest editors for helping us improve the system and this guide over the years. Thanks also to the following persons who made contributions to this guide and its previous incarnations: [Katrin Leinweber](https://github.com/katrinleinweber), [John Baumgartner](https://github.com/johnbaums), [François Michonneau](https://github.com/fmichonneau), [Christophe Dervieux](https://github.com/cderv), [Lorenzo Busetto](https://github.com/lbusett), [Ben Marwick](https://github.com/benmarwick), [Nicholas Horton](https://github.com/nicholasjhorton), [Chris Kennedy](https://github.com/ck37), [Mark Padgham](https://github.com/mpadge), [Jeroen Ooms](https://github.com/jeroen), [Sean Hughes](https://github.com/seaaan), [Jan Gorecki](https://github.com/jangorecki), [Joseph Stachelek](https://github.com/jsta), [Dean Attali](https://github.com/daattali), [Julia Gustavsen](https://github.com/jooolia), [Nicholas Tierney](https://github.com/njtierney), [Rich FitzJohn](https://github.com/richfitz), [Tiffany Timbers](https://github.com/ttimbers), [Hilmar Lapp](https://github.com/hlapp), [Miles McBain](https://github.com/milesmcbain), [Bryce Mecum](https://github.com/amoeba), [Jonathan Carroll](https://github.com/jonocarroll/), [Carl Boettiger](https://github.com/cboettig/), [Florian Privé](https://github.com/privefl), [Stefanie Butland](https://github.com/stefaniebutland), [Daniel Possenriede](https://github.com/dpprdan/), [Hadley Wickham](https://github.com/hadley/), [Mauro Lepore](https://github.com/maurolepore/), [Matthew Fidler](https://github.com/mattfidler), [Luke McGuinness](https://github.com/mcguinlu), [Aaron Wolen](https://github.com/aaronwolen), [Indrajeet Patil](https://github.com/IndrajeetPatil), [Kevin Wright](https://github.com/kwstat), [Will Landau](https://github.com/wlandau), [Hugo Gruson](https://github.com/Bisaloo), +[Hao Ye](https://github.com/ha0ye), +[Sébastien Rochette](https://github.com/statnmap). Please tell us if we forgot to acknowledge your contribution!_ diff --git a/inst/book_grooming.R b/inst/book_grooming.R deleted file mode 100644 index 58d1f8988..000000000 --- a/inst/book_grooming.R +++ /dev/null @@ -1,44 +0,0 @@ -# find all URLs -library("magrittr") - -Rmds <- fs::dir_ls(getwd(), regexp =" *.Rmd") - -find_urls <- function(filepath){ - readLines(filepath) %>% - glue::glue_collapse(sep = "\n") %>% - commonmark::markdown_html(normalize = TRUE, - extensions = TRUE) %>% - xml2::read_html() %>% - xml2::xml_find_all("//a") %>% - xml2::xml_attr("href") -> urls - - urls <- urls[!grepl("^\\#", urls)] - - tibble::tibble(filepath = filepath, - url = urls) -} - -.ok <- function(url) { - message(url) - crul::ok( - url, - verb = "get", - useragent = "Maëlle Salmon" - ) -} - -ok <- memoise::memoise( - ratelimitr::limit_rate( - .ok, - ratelimitr::rate(1, 1) - ) -) - -all_urls <- purrr::map_df(Rmds, find_urls) -all_urls <- all_urls[!grepl("", all_urls$url),] -all_urls$ok <- purrr::map_lgl( - all_urls$url, - ok - ) - -View(all_urls[!all_urls$ok,]) diff --git a/inst/spelling-check.R b/inst/spelling-check.R deleted file mode 100644 index c2286cf98..000000000 --- a/inst/spelling-check.R +++ /dev/null @@ -1,2 +0,0 @@ -spelling::spell_check_files(list.files(pattern = "\\.Rmd$"), - ignore = scan("inst/WORDLIST", what = "")) diff --git a/inst/thanks.R b/inst/thanks.R deleted file mode 100644 index a8c90490d..000000000 --- a/inst/thanks.R +++ /dev/null @@ -1,47 +0,0 @@ -library("magrittr") -index_thanks <- readLines("index.Rmd") %>% - blogdown:::split_yaml_body() %>% - .$body %>% - commonmark::markdown_xml(extensions = TRUE) %>% - xml2::read_xml() %>% - xml2::xml_find_all(xpath = './/d1:link', xml2::xml_ns(.)) %>% - xml2::xml_attr("destination") %>% - urltools::url_parse() %>% - dplyr::filter( - domain == "github.com" - ) %>% - dplyr::mutate( - path = gsub("\\/$", "", path) - ) %>% - dplyr::filter( - !grepl("\\/", path) - ) %>% - dplyr::pull(path) - -changelog_thanks <- readLines("appendix.Rmd") %>% - blogdown:::split_yaml_body() %>% - .$body %>% - commonmark::markdown_xml(extensions = TRUE) %>% - xml2::read_xml() %>% - xml2::xml_find_all(xpath = './/d1:code', xml2::xml_ns(.)) %>% - xml2::xml_text() %>% - purrr::keep(function(x) grepl("^@", x)) %>% - stringr::str_remove_all("^@") %>% - unique() - -changelog_thanks[!changelog_thanks %in% index_thanks] - -thanks2020 <- readLines("appendix.Rmd")[1:83] %>% - blogdown:::split_yaml_body() %>% - .$body %>% - commonmark::markdown_xml(extensions = TRUE) %>% - xml2::read_xml() %>% - xml2::xml_find_all(xpath = './/d1:code', xml2::xml_ns(.)) %>% - xml2::xml_text() %>% - purrr::keep(function(x) grepl("^@", x)) %>% - stringr::str_remove_all("^@") %>% - tolower() %>% - unique() - -thanks2020[!thanks2020 %in% c("includermd", "example", "sckott", "karthik", "annakrystalli", - "noamross", "stefaniebutland", "jeroen", "mpadge")] diff --git a/maintenance_changing_maintainers.Rmd b/maintenance_changing_maintainers.Rmd index 2d6fa8e44..9183e1b0a 100644 --- a/maintenance_changing_maintainers.Rmd +++ b/maintenance_changing_maintainers.Rmd @@ -28,10 +28,10 @@ We have a call for contributors section in our newsletter that comes out every t It depends; here's what to do in different scenarios: - if the old maintainer can be contacted: reach out to them, and ask for help; - - rOpenSci slack: good for getting help on specific or general problems, the #general room is where many ask questions; - - rOpenSci discussion forum: this forum is a good option, feel free to ask any questions there; - - rOpenSci staff: feel free to get in touch with one of us via slack/email/pinging us on GitHub issues, we'll be happy to help; - - of course there's general R help too if that suits your needs: StackOverflow, Twitter #rstats, etc. + - rOpenSci slack: good for getting help on specific or general problems, see the #package-maintenance channel; + - [rOpenSci discussion forum](https://discuss.ropensci.org/c/package-development/29): this forum is a good option, feel free to ask any questions there; + - [rOpenSci staff](https://ropensci.org/about/#team): feel free to get in touch with one of us via email/pinging us on GitHub issues, we'll be happy to help; + - of course there's general R help too if that suits your needs: RStudio community forum, StackOverflow, Twitter #rstats, etc. * How much can/should you change in the package? @@ -53,7 +53,7 @@ As an organization, rOpenSci is interested in making sure packages in our suite * Make contact and see what the situation is. They may say they’d like to step down as maintainer, in which case look for a new maintainer * Current maintainer is completely missing/not responding * If this happens we will try to contact the maintainer for up to one month. However, if updating the package is urgent, we may use our admin access to make changes on their behalf. -* Put a call out in the “Call for Contributors” section of the rOpenSci newsletter for a new maintainer - get in touch with Scott for this or open an issue in the [newsletter repo](https://github.com/ropensci/biweekly/) +* Put a call out in the “Call for Contributors” section of the rOpenSci newsletter for a new maintainer - open an issue in the [newsletter repo](https://github.com/ropensci/monthly/). [orphaned]: https://cran.r-project.org/src/contrib/Orphaned/README diff --git a/maintenance_collaboration.Rmd b/maintenance_collaboration.Rmd index 09fff06a6..167ccf85c 100644 --- a/maintenance_collaboration.Rmd +++ b/maintenance_collaboration.Rmd @@ -31,24 +31,26 @@ And delete the package current code of conduct if there was one. You can use issue, pull request and contributing guidelines. Having a contributing file as `.github/CONTRIBUTING.md` or `docs/CONTRIBUTING.md` is compulsory. - -Example of useful content: +An easy way to insert a template for a contributing guide is the [`use_tidy_contributing()` function from the `usethis` package](https://usethis.r-lib.org/reference/tidyverse.html), which inserts [this template](https://github.com/r-lib/usethis/blob/main/inst/templates/tidy-contributing.md) as `.github/CONTRIBUTING.md`. +A more extensive example is [this template by Peter Desmet](https://gist.github.com/peterdesmet/e90a1b0dc17af6c12daf6e8b2f044e7c), or the comprehensive [GitHub wiki pages for the mlr3 package](https://github.com/mlr-org/mlr3/wiki). +These and other templates will generally need to be modified for use with an rOpenSci package, particularly by referring and linking to our [Code of Conduct](https://ropensci.org/code-of-conduct/), as described elsewhere [in this book](#code-of-conduct). +Modifying a generic contributing guide to add a personal touch also tends to make it look less generic and more sincere. +Personal preferences in a contributing guide include: * Style preferences? You might however prefer to make style a configuration (of [lintr](https://github.com/jimhester/lintr), [styler](https://styler.r-lib.org/)) or to [fix code style yourself](https://github.com/rstudio/blogdown/pull/432#pullrequestreview-368391904) especially if you don't use a popular code style like the [tidyverse coding style](https://style.tidyverse.org/). * Infrastructure like roxygen2? -* Process preferences? Issue before a PR? - -* Scope? E.g. in skimr. - -* Sandbox account creation? Mocking in tests? Use links to external docs. +* Workflow preferences? Issue before a PR? -Example: [contributing guide template by Peter Desmet](https://gist.github.com/peterdesmet/e90a1b0dc17af6c12daf6e8b2f044e7c). +* A scope statement, like [in the skimr package](https://github.com/ropensci/skimr/blob/main/.github/CONTRIBUTING.md#understanding-the-scope-of-skimr)? -Adding a personal touch to your contributing guide might make it look less generic and therefore more sincere. +* Sandbox account creation? Mocking in tests? Linking to external docs? -CONTRIBUTING.md can also contain some details about how you acknowledge contributions (see [this section](#attributions)) and the roadmap of your package (cf [this example](https://github.com/ecohealthalliance/fasterize/blob/master/CONTRIBUTING.md)). +rOpenSci further encourages contributing guides to include a lifecycle statement clarifying visions and expectations for the future development of your package, like [in this example](https://github.com/ecohealthalliance/fasterize/blob/master/CONTRIBUTING.md#roadmap). +Statistical packages are required to have a lifecycle statement, as specified in [*General Statistical Stanards* G1.2](https://stats-devguide.ropensci.org/standards.html#documentation). +That links provides a template for a simple lifecycle statement. +CONTRIBUTING.md files can also describe how you acknowledge contributions (see [this section](#attributions)). We encourage you to direct feedback that is not a bug report or a feature request to [rOpenSci forum](https://discuss.ropensci.org/), after making sure you'd see such questions on the forum. Users can use the forum to ask questions about use and report their use cases, and you can subscribe to individual categories and tags to receive notifications about your package. Feel free to mention this in the docs of your package and/or the contributing guidelines/issue template. Please direct your users to tag posts with the package name. @@ -93,13 +95,17 @@ If your problem is _recruiting_ collaborators, you can post an open call like Ji ### Working with collaborators (including yourself) {#gitflow} -You could implement the "[gitflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)" philosophy as explained by Amanda Dobbyn in [this blog post](https://ropensci.org/blog/2018/04/20/monkeydo/#gitflow). In a nutshell, +[Branches](https://happygitwithr.com/git-branches.html) are cheap. Use them extensively when developing features, testing out new ideas, fixing problems. -* Keep the default branch (main or master) as shippable as much as possible +One of the branches is the default / main branch, where, if you follow [trunk-based development](https://www.atlassian.com/continuous-delivery/continuous-integration/trunk-based-development), you "merge small, frequent updates". +See also [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow) and [GitLab flow](https://docs.gitlab.com/ee/topics/gitlab_flow.html) docs. +You might want to pair the frequent incrementing of version numbers (in `DESCRIPTION`). +One particular aspect of working with collaborators is reviewing pull requests, with some useful guidance in: -* [Branches](https://happygitwithr.com/git-branches.html) are cheap. Use them extensively when developing features, testing out new ideas, fixing problems. +* [The Art of Giving and Receiving Code Reviews (Gracefully), by Alex Hill](https://www.alexandra-hill.com/2018/06/25/the-art-of-giving-and-receiving-code-reviews/) +* [GitHub documentation about PR reviews](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews) -One particular aspect of working with collaborators is reviewing pull requests. Even if not adopting gitflow it might make sense for repo collaborators to make PRs and have them reviewed, and in general PRs by external developers will need to be assessed. Sometimes you'll be fine just reading the changes and trusting [Continuous integration](#ci). Sometimes you'll need more exploration and even extension of the PR in which case we recommend reading ["Explore and extend a pull request" in happygitwithr.com](https://happygitwithr.com/pr-extend.html). +For making and reviewing pull requests we recommend [exploring usethis functions](https://usethis.r-lib.org/articles/pr-functions.html). ### Be generous with attributions {#attributions} @@ -123,9 +129,9 @@ Please do not list editors as contributors. Your participation in and contributi If you give someone write permissions to the repository, -* please contact one of [the editors](#associateditors) so that this new contributor might get **invited to rOpenSci's "ropensci" GitHub organization** (instead of being [outside collaborators](https://help.github.com/articles/repository-permission-levels-for-an-organization/#outside-collaborators)) +* please contact a [staff member](https://ropensci.org/about#team) so that this new contributor might get **invited to rOpenSci's "ropensci" GitHub organization** (instead of being [an outside collaborator](https://help.github.com/articles/repository-permission-levels-for-an-organization/#outside-collaborators)) -* please contact rOpenSci community manager [Stefanie Butland](https://github.com/stefaniebutland) so that this new contributor might get get **invited to rOpenSci Slack workspace**. +* please contact rOpenSci's [community manager or another staff member](https://ropensci.org/about#team) so that this new contributor might get get **invited to rOpenSci Slack workspace**. ## Further resources diff --git a/maintenance_curation.Rmd b/maintenance_curation.Rmd index 631b55cee..e69978ef0 100644 --- a/maintenance_curation.Rmd +++ b/maintenance_curation.Rmd @@ -130,10 +130,6 @@ at the time of submission to be reviewed. pages will `display these with `"type": "archived"` that were either peer-reviewed or staff-maintained. -- Archived packages may be unarchived if authors or a new person - opt to resume maintenance. For that please [contact rOpenSci](https://ropensci.org/contact/). - They are transferred to the ropenscilabs organization. - ## Legacy acquired packages "Legacy" packages are packages not created or maintained by rOpenSci @@ -196,15 +192,6 @@ at unconferences - If archived, non-R-packages will move to "ropensci-archive" following [transfer guidance](#archivalguidance). -### General guidance for transfer to ropensci-archive or authors account {#archivalguidance} - -- Update the README (remove installation instructions, add reason for archival, - link to this guidance). -- Add a repostatus.org badge to the README (unsupported for former released packages, - or abandoned if the package always only was a concept or WIP). -- Close issues with a sentence explaining the situation and linking to this guidance. -- Disable issues (under repo settings). - ## Books rOpenSci books are long-form documentation, often bookdown-formatted, diff --git a/maintenance_evolution.Rmd b/maintenance_evolution.Rmd index 8ddc8cba1..8229be3a7 100644 --- a/maintenance_evolution.Rmd +++ b/maintenance_evolution.Rmd @@ -1,7 +1,7 @@ # Package evolution - changing stuff in your package {#evolution} ```{block, type='summaryblock'} -This chapter presents our guidance for changing stuff in your package: changing parameter names, changing function names, deprecating functions. +This chapter presents our guidance for changing stuff in your package: changing parameter names, changing function names, deprecating functions, and even retiring and archiving packages. _This chapter was initially contributed as a tech note on rOpenSci website by [Scott Chamberlain](https://github.com/sckott); you can read the original version [here](https://ropensci.org/technotes/2017/01/05/package-evolution/)._ ``` @@ -13,7 +13,7 @@ Everyone's free to have their own opinion about how freely parameters/functions/ ## The lifecycle package This chapter presents solutions that do not require the lifecycle package but you might still find it useful. -We recommend [reading the lifecycle documentation](https://lifecycle.r-lib.org/articles/lifecycle.html). +We recommend [reading the lifecycle documentation](https://lifecycle.r-lib.org/articles/stages.html). ## Parameters: changing parameter names @@ -196,3 +196,29 @@ You don't have to change the tests of deprecated functions until they are made d Once a function is made defunct, its tests are simply removed. +## Archiving packages {#archivalguidance} + +Software generally has a finite lifespan, and packages may eventually need to be archived. Archived packages are [archived](https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories) and moved to a dedicated GitHub organization, [ropensci-archive](https://github.com/ropensci-archive). Prior to archiving, the contents of the README file should be moved to an alternative location (such as "README-OLD.md"), and replaced with minimal contents including something like the following: + + +``` md +# + +[![Project Status: Unsupported](https://www.repostatus.org/badges/latest/unsupported.svg)](https://www.repostatus.org/#unsupported) +[![Peer-review badge](https://badges.ropensci.org/_status.svg)](https://github.com/ropensci/software-review/issues/) + +This package has been archived. The former README is now in [README-old](). +``` + +The repo status badge should be "unsupported" for formerly released packages, or "abandoned" for former concept or WIP packages, in which case the badge code above should be replaced with: +``` md +[![Project Status: Abandoned](https://www.repostatus.org/badges/latest/abandoned.svg)](https://www.repostatus.org/#abandoned) +``` + +An example of a minimal README in an archived package is in [ropensci-archive/monkeylearn](https://github.com/ropensci-archive/monkeylearn/blob/master/README.md). Once the README has been copied elsewhere and reduced to minimal form, the following steps should be followed: + +- [ ] Close issues with a sentence explaining the situation and linking to this guidance. +- [ ] Archive the repository on GitHub (also under repo settings). +- [ ] Transfer the repository to [ropensci-archive](https://github.com/ropensci-archive), or request an [rOpenSci staff member](https://ropensci.org/about/#team) to transfer it (you can email `info@ropensci.org`). + +Archived packages may be unarchived if authors or a new person opt to resume maintenance. For that please contact rOpenSci. They are transferred to the ropenscilabs organization. diff --git a/maintenance_marketing.Rmd b/maintenance_marketing.Rmd index 7909e8141..65b998c3b 100644 --- a/maintenance_marketing.Rmd +++ b/maintenance_marketing.Rmd @@ -12,7 +12,7 @@ We will help you promoting your package but here are some more things to keep in * Tweet about it using the "#rstats" hashtag and tag rOpenSci! This might help with contributor/user engagement. [Example](https://twitter.com/opencpu/status/1003934871830622208). - * Consider submitting a short post about the release to [rOpenSci tech notes](https://ropensci.org/technotes/). Contact Stefanie Butland, rOpenSci Community Manager, (e.g. via Slack or stefanie@ropensci.org). Refer to [the guidelines about contributing a blog post](https://blogguide.ropensci.org)). + * Consider submitting a short post about the release to [rOpenSci tech notes](https://ropensci.org/technotes/). Contact rOpenSci Community Manager, (e.g. via Slack or info@ropensci.org). Refer to [the guidelines about contributing a blog post](https://blogguide.ropensci.org)). * Submit your package to lists of packages such as [CRAN Task Views](https://cran.r-project.org/web/views/), and [rOpenSci non-CRAN Task Views](https://github.com/search?utf8=%E2%9C%93&q=user%3Aropensci+%22task+view%22&type=Repositories&ref=searchresults). diff --git a/maintenance_releases.Rmd b/maintenance_releases.Rmd index dce4d2b56..6821dee90 100644 --- a/maintenance_releases.Rmd +++ b/maintenance_releases.Rmd @@ -37,5 +37,5 @@ foobar 0.2.0 (2016-04-01) a description of the new feature, improvement, bug fix, or deprecated function/feature. Link to any related GitHub issue like `(#12)`. The `(#12)` will resolve on GitHub in Releases to a link to that issue in the repo. * After you have added a `git tag` and pushed up to GitHub, add the news items for that tagged version to the Release notes of a release in your GitHub repo with a title like `pkgname v0.1.0`. See [GitHub docs about creating a release](https://help.github.com/articles/creating-releases/). -* New CRAN releases will be tweeted about automatically by [roknowtifier](https://twitter.com/roknowtifier) and written about [in our biweekly newsletter](https://ropensci.github.io/biweekly/) but see [next chapter about marketing](#marketing) about how to inform more potential users about the release. +* New CRAN releases will be tweeted about automatically by [roknowtifier](https://twitter.com/roknowtifier) and written about [in our biweekly newsletter](https://news.ropensci.org/) but see [next chapter about marketing](#marketing) about how to inform more potential users about the release. * For more guidance about the NEWS file we suggest reading the [tidyverse NEWS style guide](https://style.tidyverse.org/news.html). diff --git a/pkg_building.Rmd b/pkg_building.Rmd index 79f2b0921..b515ff93e 100644 --- a/pkg_building.Rmd +++ b/pkg_building.Rmd @@ -68,8 +68,8 @@ The [`tabulizer` package](https://github.com/ropensci/tabulizer) e.g. has an int ## CITATION file -* Create and populate the CITATION file. It's easy to create a boilerplate with `usethis::use_citation()`. -* Archive each release of your GitHub repo on Zenodo and add the [Zenodo top-level DOI](https://help.zenodo.org/#versioning) to the CITATION file. +* If your package does not yet have a CITATION file, you can create one with `usethis::use_citation()`, and populate it with values generated by the `citation()` function. +* If you archive each release of your GitHub repo on Zenodo, add the [Zenodo top-level DOI](https://help.zenodo.org/#versioning) to the CITATION file. * If one day [**after** review at rOpenSci](#authors-guide) you publish a software publication about your package, add it to the CITATION file. * Less related to your package itself but to what supports it: if your package wraps a particular resource such as data source or, say, statistical algorithm, remind users of how to cite that resource via e.g. `citHeader()`. [Maybe even add the reference for the resource](https://discuss.ropensci.org/t/citation-of-original-article-when-implementing-specific-methods/2312). @@ -115,7 +115,7 @@ bibentry(bibtype = "Manual", " https://CRAN.R-project.org/package=nasapower") ``` - +* You could also create and store a `CITATION.cff` thanks to the [cffr package](https://docs.ropensci.org/cffr/). It also provides a [GitHub Action workflow](https://docs.ropensci.org/cffr/reference/cff_gha_update.html) to keep the `CITATION.cff` file up-to-date. ## README @@ -133,8 +133,6 @@ bibentry(bibtype = "Manual", If you use another repo status badge such as a [lifecycle](https://www.tidyverse.org/lifecycle/) badge, please also add a [repostatus.org](https://www.repostatus.org/) badge. [Example of a repo README with two repo status badges](https://github.com/ropensci/ijtiff#ijtiff-). -In all cases, for adding repostatus.org badges you can use the [`rodev::use_repostatus_badge()`](https://docs.ropensci.org/rodev/reference/use_repostatus_badge.html) function. - * Once you have submitted a package and it has passed editor checks, add a peer-review badge via ``` @@ -205,7 +203,7 @@ can be found at *link*". * All functions should document the type of object returned under the `@return` heading. -* We recommend using the `@family` tag in the documentation of functions to allow their grouping in the documentation of the installed package and potentially in the package's website, see [the "manual" section of The R Packages book](https://r-pkgs.org/man.html) and [the "function grouping" section of the present chapter](#function-grouping) for more details. +- Documentation should support user navigation by including useful cross-links between related functions and documenting related functions together in groups or in common help pages. The `@seealso` and `@family` tags (the latter of which automatically creates “See also” links and [can help group](https://pkgdown.r-lib.org/reference/build_reference.html) functions together on pkgdown sites), are recommended for this purpose. See [the "manual" section of The R Packages book](https://r-pkgs.org/man.html) and [the "function grouping" section of the present chapter](#function-grouping) for more details. * You could re-use documentation pieces (e.g. details about authentication, related packages) across the vignettes/README/man pages. A possible approach for that is the use of [R Markdown fragments, relying on knitr use of child documents so you can store the re-used parts in a folder in man/, and call them from both the README and the vignette](https://www.garrickadenbuie.com/blog/dry-vignette-and-readme/) as well [as in man pages by using the `@includeRmd` tag available from `roxygen 0.7.0`](https://roxygen2.r-lib.org/articles/rd.html#including-external--rmd-md-files). @@ -235,7 +233,7 @@ There are a few elements we'd like to underline here. ### Automatic deployment of the documentation website {#docsropensci} -You only need to worry about automatic deployment of your website until approval and transfer of your package repo to the ropensci organization; indeed, after that a pkgdown website will be built for your package after each push to the GitHub repo. You can find the status of these builds at `https://dev.ropensci.org/job/package_name`, e.g. [for `magick`](https://dev.ropensci.org/job/magick); and the website at `https://docs.ropensci.org/package_name`, e.g. [for `magick`](https://docs.ropensci.org/magick). The website build will use your pkgdown config file if you have one, except for the styling that will use the [`rotemplate` package](https://github.com/ropensci-org/rotemplate/). The resulting website will have search enabled by Algolia. Please report bugs, questions and feature requests about the central builds at https://github.com/ropensci/docs/ and about the template at https://github.com/ropensci/rotemplate/. +You only need to worry about automatic deployment of your website until approval and transfer of your package repo to the ropensci organization; indeed, after that a pkgdown website will be built for your package after each push to the GitHub repo. You can find the status of these builds at `https://dev.ropensci.org/job/package_name`, e.g. [for `magick`](https://dev.ropensci.org/job/magick); and the website at `https://docs.ropensci.org/package_name`, e.g. [for `magick`](https://docs.ropensci.org/magick). The website build will use your pkgdown config file if you have one, except for the styling that will use the [`rotemplate` package](https://github.com/ropensci-org/rotemplate/). The resulting website will have a local search bar. Please report bugs, questions and feature requests about the central builds at https://github.com/ropensci/docs/ and about the template at https://github.com/ropensci/rotemplate/. *If your package vignettes need credentials (API keys, tokens, etc.) to knit, you might want to [precompute them](https://ropensci.org/technotes/2019/12/08/precompute-vignettes/) since credentials cannot be used on the docs server.* @@ -246,13 +244,14 @@ Before submission and before transfer, you could use the [approach documented by When your package has many functions, use grouping in the reference, which you can do more or less automatically. If you use `roxygen2` above version 6.1.1, you should use the `@family` tag in your functions documentation to indicate grouping. This will give you links between functions in the local documentation of the installed package ("See also" section) _and_ allow you to use the `pkgdown` `has_concept` function in the config file of your website. Non-rOpenSci example courtesy of [`optiRum`](https://github.com/lockedata/optiRum): [family tag](https://github.com/lockedata/optiRum/blob/master/R/APR.R#L17), [`pkgdown` config file](https://github.com/lockedata/optiRum/blob/master/_pkgdown.yml) and [resulting reference section](https://itsalocke.com/optirum/reference/). + To customize the text of the cross-reference title created by roxygen2 (`Other {family}:`), refer to [roxygen2 docs regarding how to provide a `rd_family_title` list in `man/roxygen/meta.R`](https://roxygen2.r-lib.org/articles/rd.html#cross-references). Less automatically, see the example of [`drake` website](https://docs.ropensci.org/drake/) and [associated config file ](https://github.com/ropensci/drake/blob/master/_pkgdown.yml). ### Branding of authors -You can make the names of (some) authors clickable by adding their URL, and you can even replace their names with a logo (think rOpenSci... or your organisation/company!). See [`pkgdown` documentation](https://pkgdown.r-lib.org/reference/build_home.html?q=authors#yaml-config-authors) and this example in the wild: [`pkgdown` config file](https://github.com/ropensci/rodev/blob/f07fdead39762b332bc1df63e470cdc271d696e0/_pkgdown.yml#L1), [resulting website](https://docs.ropensci.org/rodev/). +You can make the names of (some) authors clickable by adding their URL, and you can even replace their names with a logo (think rOpenSci... or your organisation/company!). See [`pkgdown` documentation](https://pkgdown.r-lib.org/reference/build_home.html?q=authors#yaml-config-authors). ### Tweaking the navbar @@ -282,9 +281,19 @@ The `DESCRIPTION` file of a package should list package authors and contributors comment = "Bea reviewed the package (v. X.X.XX) for rOpenSci, see "), ``` -Only include reviewers after asking for their consent. Read more in [this blog post "Thanking Your Reviewers: Gratitude through Semantic Metadata"](https://ropensci.org/blog/2018/03/16/thanking-reviewers-in-metadata/). Note that 'rev' will raise a CRAN NOTE unless the package is built using R v3.5. Make sure you use `roxygen2`'s latest CRAN version. +Only include reviewers after asking for their consent. Read more in [this blog post "Thanking Your Reviewers: Gratitude through Semantic Metadata"](https://ropensci.org/blog/2018/03/16/thanking-reviewers-in-metadata/). Please do not list editors as contributors. Your participation in and contribution to rOpenSci is thanks enough! + +### Authorship of included code {#authorship-included-code} + +Many packages include code from other software. Whether entire files or single functions are included from other packages, rOpenSci packages should follow [the CRAN *Repository Policy*](https://cran.r-project.org/web/packages/policies.html): -Please do not list editors as contributors. Your participation in and contribution to rOpenSci is thanks enough! +> The ownership of copyright and intellectual property rights of all components of the package must be clear and unambiguous (including from the authors specification in the DESCRIPTION file). Where code is copied (or derived) from the work of others (including from R itself), care must be taken that any copyright/license statements are preserved and authorship is not misrepresented. +> +> Preferably, an ‘Authors@R’ field would be used with ‘ctb’ roles for the authors of such code. Alternatively, the ‘Author’ field should list these authors as contributors. +> +> Where copyrights are held by an entity other than the package authors, this should preferably be indicated via ‘cph’ roles in the ‘Authors@R’ field, or using a ‘Copyright’ field (if necessary referring to an inst/COPYRIGHTS file). +> +> Trademarks must be respected. ## Licence @@ -299,17 +308,25 @@ For more explanations around licensing, refer to the [R packages book](https://r * It is good practice to write unit tests for all functions, and all package code in general, ensuring key functionality is covered. Test coverage below 75% will likely require additional tests or explanation before being sent for review. -* We recommend using `testthat` for writing tests. Strive to write tests as you write each new function. This serves the obvious need to have proper testing for the package, but allows you to think about various ways in which a function can fail, and to _defensively_ code against those. [More information](https://r-pkgs.org/tests.html). +* We recommend using [testthat](https://testthat.r-lib.org/) for writing tests. Strive to write tests as you write each new function. This serves the obvious need to have proper testing for the package, but allows you to think about various ways in which a function can fail, and to _defensively_ code against those. [More information](https://r-pkgs.org/tests.html). + +* Tests should be easy to understand. We suggest reading the blog post [_"Why Good Developers Write Bad Unit Tests"_](https://mtlynch.io/good-developers-bad-tests/) by Michael Lynch. * Packages with Shiny apps should use a unit-testing framework such as [`shinytest`](https://rstudio.github.io/shinytest/articles/shinytest.html) to test that interactive interfaces behave as expected. -* For testing your functions creating plots, we suggest using [`vdiffr`](https://cran.rstudio.com/web/packages/vdiffr/index.html), an extension of the `testthat` package; or [testthat snapshot tests](https://testthat.r-lib.org/articles/snapshotting.html). +* For testing your functions creating plots, we suggest using [vdiffr](https://cran.rstudio.com/web/packages/vdiffr/index.html), an extension of the testthat package; or [testthat snapshot tests](https://testthat.r-lib.org/articles/snapshotting.html). -* If your package interact with web resources (web APIs and other sources of data on the web) you might find the [HTTP testing in R book by Scott Chamberlain and Maëlle Salmon](https://books.ropensci.org/http-testing/) relevant. +* If your package interacts with web resources (web APIs and other sources of data on the web) you might find the [HTTP testing in R book by Scott Chamberlain and Maëlle Salmon](https://books.ropensci.org/http-testing/) relevant. Packages helping with HTTP testing (corresponding HTTP clients): + * [httptest2](https://enpiar.com/httptest2/) ([httr2](https://httr2.r-lib.org/)); + * [httptest](https://enpiar.com/r/httptest/) ([httr](https://httr.r-lib.org/)); + * [vcr](https://docs.ropensci.org/vcr/) ([httr](https://httr.r-lib.org/), [crul](https://docs.ropensci.org/crul)); + * [webfakes](https://webfakes.r-lib.org/) ([httr](https://httr.r-lib.org/), [httr2](https://httr2.r-lib.org/), [crul](https://docs.ropensci.org/crul), [curl](https://github.com/jeroen/curl)). -* Once you've set up CI, use your package's code coverage report (cf [this section of our book](#coverage)) to identify untested lines, and to add further tests. +* testthat has a function `skip_on_cran()` that you can use to not run tests on CRAN. We recommend using this on all functions that are API calls since they are quite likely to fail on CRAN. These tests should still run on continuous integration. Note that from testthat 3.1.2 `skip_if_offline()` automatically calls `skip_on_cran()`. More info on [CRAN preparedness for API wrappers](https://books.ropensci.org/http-testing/cran-preparedness.html). + +* If your package interacts with a database you might find [dittodb](https://docs.ropensci.org/dittodb) useful. -* `testthat` has a function `skip_on_cran()` that you can use to not run tests on CRAN. We recommend using this on all functions that are API calls since they are quite likely to fail on CRAN. These tests should still run on continuous integration. +* Once you've set up [continuous interaction (CI)](#ci), use your package's code coverage report (cf [this section of our book](#coverage)) to identify untested lines, and to add further tests. * Even if you use [continuous integration](#ci), we recommend that you run tests locally prior to submitting your package, as some tests are often skipped (you may need to set `Sys.setenv(NOT_CRAN="true")` in order to ensure all tests are run). In addition, we recommend that prior to submitting your package, you use MangoTheCat's [**goodpractice**](https://github.com/MangoTheCat/goodpractice/) package to check your package for likely sources of errors, and run `spelling::spell_check_package()` to find spelling errors in documentation. @@ -362,8 +379,10 @@ An example of bad practice would be for a developer to consider the versions of * Small, simple functions from a dependency package may be better copied into your own package if the dependency if you are using only a few functions - in an otherwise large or heavy dependency. On the other hand, complex functions - with many edge cases (e.g. parsers) require considerable testing and vetting. + in an otherwise large or heavy dependency. (See [*Authorship* section + above](#authorship-included-code) for how to acknowledge original authors + of copied code.) On the other hand, complex functions with many edge + cases (e.g. parsers) require considerable testing and vetting. * An common example of this is in returning tidyverse-style "tibbles" from package functions that provide data. @@ -393,12 +412,14 @@ rather than one where it is re-exported. For instance many functions in **devtoo ## Recommended scaffolding -* For HTTP requests we recommend using [curl][], [crul][], or [httr][] over [RCurl][]. If you like low level clients for HTTP, [curl][] is best, whereas [crul][] or [httr][] are better for higher level access. [crul][] is maintained by rOpenSci. We recommend the rOpenSci maintained packages [webmockr][] for mocking HTTP requests, and [vcr][] for caching HTTP requests in package tests. +* For HTTP requests we recommend using [curl][], [crul][], [httr][] or [httr2][] over [RCurl][]. If you like low level clients for HTTP, [curl][] is best, whereas [crul][] or [httr][] are better for higher level access. [crul][] is maintained by rOpenSci. We recommend the rOpenSci maintained packages [webmockr][] for mocking HTTP requests, and [vcr][] for caching HTTP requests in package tests. * For parsing JSON, use [jsonlite][] instead of [rjson][] or [RJSONIO][]. * For parsing, creating, and manipulating XML, we strongly recommend [xml2][] for most cases. [You can refer to Daniel Nüst's notes about migration from XML to xml2](https://gist.github.com/nuest/3ed3b0057713eb4f4d75d11bb62f2d66). +* For spatial data, the [sp][] package should be considered deprecated in favor of [sf][], and the packages [rgdal][], [maptools][], and [rgeos][] will be retired by the end of 2023. We recommend use of the spatial suites developed by the [r-spatial](https://github.com/r-spatial) and [rspatial](https://github.com/rspatial) communities. See [this GitHub issue](https://github.com/ropensci/software-review-meta/issues/47) for relevant discussions. + ## Version Control @@ -427,7 +448,7 @@ Once your package is on CRAN, it will be [regularly checked on different platfor * the [`foghorn` package](https://fmichonneau.github.io/foghorn/). -* the [CRAN checks API](https://github.com/ropenscilabs/cchecksapi) maintained by rOpenSci, that provides [badges](https://github.com/ropenscilabs/cchecksapi#badges). You can add one of them to the README of your package via [`rodev::use_cchecks_badge()`](https://docs.ropensci.org/rodev/reference/use_cchecks_badge.html). +* the [CRAN checks API](https://github.com/ropenscilabs/cchecksapi) maintained by rOpenSci, that provides [badges](https://github.com/ropenscilabs/cchecksapi#badges). ## Bioconductor gotchas @@ -439,11 +460,13 @@ If you intend your package to be submitted to, or if your package is on, Biocond * Before submitting a package use the [**goodpractice**](https://github.com/MangoTheCat/goodpractice) package (`goodpractice::gp()`) as a guide to improve your package, since most exceptions to it will need to be justified. E.g. the use of `foo` might be generally bad and therefore flagged by `goodpractice` but you had a good reason to use it in your package. +- Read, incorporate, and act on advice from the [*Collaboration Guide* chapter](#collaboration). + ### Learning about package development #### Books -* [Hadley Wickham and Jenny Bryan's *R packages* book](https://r-pkgs.org/) is an excellent, readable resource on package development which is available for [free online](https://r-pkgs.org/) (and [print -- link to former version by Hadley Wickham as the new version is not published yet as of June 2019](https://amzn.com/1491910593?tag=r-pkgs-20)). +* [Hadley Wickham and Jenny Bryan's *R packages* book](https://r-pkgs.org/) is an excellent, readable resource on package development which is available for [free online](https://r-pkgs.org/) (and [print -- link to former version by Hadley Wickham as the new version is not published yet as of June 2022](https://www.amazon.com/Packages-Organize-Test-Document-Share/dp/1491910593)). * [Writing R Extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html) is the canonical, usually most up-to-date, reference for creating R packages. @@ -455,10 +478,20 @@ If you intend your package to be submitted to, or if your package is on, Biocond * [Hilary Parker's famous blog post *Writing an R package from scratch*](https://hilaryparker.com/2014/04/29/writing-an-r-package-from-scratch/) or [its updated version by Tomas Westlake](https://r-mageddon.netlify.com/post/writing-an-r-package-from-scratch/) that shows how to do the same more efficiently using `usethis`. -* [this workflow description by Emil Hvitfeldt](https://www.hvitfeldt.me/blog/usethis-workflow-for-package-development/). +* [this workflow description by Emil Hvitfeldt](https://www.emilhvitfeldt.com/post/2018-09-02-usethis-workflow-for-package-development/). * [This pictorial by Matthew J Denny](https://www.mjdenny.com/R_Package_Pictorial.html). +#### Blogs + +* [R-hub blog](https://blog.r-hub.io/post). + +* Some posts of the [rOpenSci blog](https://ropensci.org/archive/) e.g. ["How to precompute package vignettes or pkgdown articles"](https://ropensci.org/blog/2019/12/08/precompute-vignettes/). + +* Package Development Corner section of [rOpenSci newsletter](https://ropensci.org/news/). + +* Some posts of the [tidyverse blog](https://www.tidyverse.org) e.g. ["Upgrading to testthat edition 3"](https://www.tidyverse.org/blog/2022/02/upkeep-testthat-3/). + #### MOOCs There is a [Coursera specialization corresponding to the book by Roger Peng, Sean Kross and Brooke Anderson](https://fr.coursera.org/specializations/r), with a course specifically about R packages. @@ -467,10 +500,16 @@ There is a [Coursera specialization corresponding to the book by Roger Peng, Sea [curl]: https://github.com/jeroen/curl/ [RCurl]: https://cran.rstudio.com/web/packages/RCurl/ [crul]: https://github.com/ropensci/crul/ -[httr]: https://cran.rstudio.com/web/packages/httr/ +[httr]: https://httr.r-lib.org +[httr2]: https://httr2.r-lib.org [webmockr]: https://github.com/ropensci/webmockr/ [vcr]: https://github.com/ropensci/vcr/ [jsonlite]: https://github.com/jeroen/jsonlite [rjson]: https://cran.rstudio.com/web/packages/rjson/ [RJSONIO]: https://cran.rstudio.com/web/packages/RJSONIO/ [xml2]: https://cran.rstudio.com/web/packages/xml2/ +[sp]: https://github.com/edzer/sp/ +[sf]: https://r-spatial.github.io/sf/ +[rgdal]: https://cran.r-project.org/web/packages/rgdal/index.html +[maptools]: https://cran.r-project.org/web/packages/maptools/index.html +[rgeos]: https://cran.r-project.org/web/packages/rgeos/index.html diff --git a/pkg_ci.Rmd b/pkg_ci.Rmd index 51344ee09..4d2da85d2 100644 --- a/pkg_ci.Rmd +++ b/pkg_ci.Rmd @@ -12,17 +12,7 @@ All rOpenSci packages must use one form of continuous integration. This ensures Both test status and code coverage should be reported via badges in your package README. -## How to use continuous integration? - -The `usethis` package offers a few functions for continuous integration setup, see [the documentation](https://usethis.r-lib.org/reference/ci.html). - -Details will be provided below for different services. - -## Which continuous integration service(s)? {#whichci} - -Different continuous integration services will support builds on different operating systems. - -R packages should have CI for all platforms when they contain: +R packages should have CI for all operating systems (Linux, Mac OSX, Windows) when they contain: * Compiled code @@ -36,12 +26,15 @@ R packages should have CI for all platforms when they contain: * Anything with file system / path calls -In case of any doubt regarding the applicability of these criteria to your package, it's better to add CI for all platforms, and most often not too much hassle. +In case of any doubt regarding the applicability of these criteria to your package, it's better to add CI for all operating systems. Most CI services standards setups for R packages allow this with not much hassle. + +## Which continuous integration service(s)? {#whichci} + +There are a number of continuous integration services, including standalone services (CircleCI, AppVeyor), and others integrated into code hosting or related services (GitHub Actions, GitLab, AWS Code Pipeline). Different services support different operating system configurations. -### GitHub Actions (Linux, Mac OSX, Windows) +[GitHub Actions](https://github.com/features/actions) is a convenient option for many R developers who already use GitHub as it is integrated into the platform and supports all needed operating Systems. There are [actions supported for the R ecosystem](https://github.com/r-lib/actions/), as well and first-class support in the [{usethis}](https://usethis.r-lib.org/reference/github_actions.html) package. All packages submitted to rOpenSci for peer review are checked by our own [`pkgcheck` system](https://docs.ropensci.org/pkgcheck), described further in the [Guide for Authors](#authors-guide). These checks are also provided as a GitHub Action in the [`ropensci-review-tools/pkgcheck-action` repository](https://github.com/ropensci-review-tools/pkgcheck-action). Packages authors are encouraged to use that action to confirm prior to submission that a package passes all of our checks. See [our blog post](https://ropensci.org/blog/2022/02/01/pkgcheck-action/) for more information. -[GitHub Actions](https://github.com/features/actions) is a new CI service for which there are [examples and actions for R packages](https://github.com/r-lib/actions/), as well as [usethis support](https://usethis.r-lib.org/reference/use_github_action.html). -It is gaining popularity. +[usethis supports CI setup for other systems](https://usethis.r-lib.org/reference/ci.html), though these functions are soft-deprecated. rOpenSci also supports the [circle](https://docs.ropensci.org/circle/) package, which aids in setting up CircleCI pipelines, and the [tic](https://docs.ropensci.org/tic/) package for building more complicated CI pipelines. #### Testing using different versions of R @@ -82,7 +75,7 @@ We no longer transfer AppVeyor projects to ropensci AppVeyor account so after tr ## Test coverage {#coverage} -Continuous integration should also include reporting of test coverage via a testing service such as [Codecov](https://codecov.io/) or [Coveralls](https://coveralls.io/). See the [README for the **covr** package](https://github.com/jimhester/covr) for instructions, as well +Continuous integration should also include reporting of test coverage via a testing service such as [Codecov](https://codecov.io/) or [Coveralls](https://coveralls.io/). See the [README for the **covr** package](https://github.com/r-lib/covr) for instructions, as well as `usethis::use_coverage()`. If you run coverage on several CI services [the results will be merged](https://docs.codecov.io/docs/merging-reports). diff --git a/pkg_security.Rmd b/pkg_security.Rmd index 2ac6fc069..8967e8b75 100644 --- a/pkg_security.Rmd +++ b/pkg_security.Rmd @@ -6,7 +6,15 @@ This work-in-progress chapter includes [guidance about managing secrets in packa ## Miscellaneous -* We recommend you [secure your GitHub account with 2FA](https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/). +We recommend the article [Ten quick tips for staying safe online](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1008563) by Danielle Smalls and Greg Wilson. + +## GitHub access security + +* We recommend you [secure your GitHub account with two-factor (authentication) 2FA](https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/). It is *compulsory* for all ropensci GitHub organization members and outside collaborators so make sure to enable it before your package is approved. + +* We also recommend you regularly check who has access to your package repository, and that you prune any unused access (such as from former collaborators). + +## https * If the web service your package wraps has either https or http, opt for https. @@ -26,7 +34,7 @@ Say your package needs an API key for making requests on behalf of users of your * Do not print the API key even in verbose mode in any message, warning, error. -* In the GitHub issue template, it should be stated not to share any credentials (it's the case for [rOpenSci issue template](https://docs.ropensci.org/rodev/reference/use_ro_github.html)). If an user of your package accidentally shares credentials in an issue, make sure they're aware of that so they can revoke the key (i.e. ask them explicitly in an answer whether they realized they shared their key). +* In the GitHub issue template, it should be stated not to share any credentials. If an user of your package accidentally shares credentials in an issue, make sure they're aware of that so they can revoke the key (i.e. ask them explicitly in an answer whether they realized they shared their key). ### Secrets in packages and development @@ -71,5 +79,3 @@ Useful security resources: * [the `notary` package](https://ropensci.org/blog/2017/07/25/notary/); * [`gargle` article "Managing tokens securely"](gargle.r-lib.org/articles/articles/managing-tokens-securely.html) - -* elements outlined in [this bookdown](https://ropenscilabs.github.io/r-security-practices/) ([repo](https://github.com/ropenscilabs/r-security-practices)) started at the unconf 2017. diff --git a/softwarereview_author.Rmd b/softwarereview_author.Rmd index 87a3d81d3..e84c046fb 100644 --- a/softwarereview_author.Rmd +++ b/softwarereview_author.Rmd @@ -4,26 +4,48 @@ This concise guide presents the software peer review process for you as a package author. ``` -- Consult our [policies](#policies) see if your package meets our criteria for fitting into our suite and is not overlapping with other packages. +## Planning a Submission (or a Pre-Submission Enquiry) + +- Do you expect to maintain your package for at least 2 years, or to be able to identify a new maintainer? +- Consult our [policies](#policies) see if your package meets our criteria for fitting into our suite and does not overlap with other packages. - If you are unsure whether a package meets our criteria, feel free to open an issue as a pre-submission inquiry to ask if the package is appropriate. -- Use [pkgcheck](https://docs.ropensci.org/pkgcheck/), read and follow [our packaging style guide](#building), [reviewer's guide](#preparereview) to ensure your package meets our style and quality criteria. - - If you feel your package is in scope for the - [Journal of Open-Source Software](https://joss.theoj.org/) (JOSS), 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. - Please consider the best time in your package's development to submit. Your package should be sufficiently mature so that reviewers are able to review all essential aspects, but keep in mind that review may result in major changes. - - 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. - - If you use [repostatus.org badges](https://www.repostatus.org/) (which we recommend), submit when you're ready to get an _Active_ instead of _WIP_ badge. Similarly, if you use [lifecycle badges](https://www.tidyverse.org/lifecycle/), submission should happen if the package is at least _Maturing_. - - At the submission stage, all major functions should be stable enough to be fully documented and tested; the README should make a strong case for the package (the editors will read it to e.g. evaluate this as in scope or not.). - We strongly suggest submitting your package for review _before_ publishing on CRAN or submitting a software paper describing the package to a journal. Review feedback may result in major improvements and updates to your package, including renaming and breaking changes to functions. - - Your package will continue to evolve after review, this book [provides guidance about the topic](#evolution). -- In your initial (pre-)submission and README, strive to explain your package's functionality and aim assuming little to no domain knowledge from the reader. E.g. if you wrote something to interact with knitr engines, what's a knitr engine? -- Do not submit your package for review while it or an associated manuscript is also under review at another venue, as this may result on conflicting requests for changes. -- Next, [open a new issue](https://github.com/ropensci/software-review/issues/new/choose) in -the software review repository and fill out the template. + - Do not submit your package for review while it or an associated manuscript is also under review at another venue, as this may result in conflicting requests for changes. +- Please also consider the time and effort needed to respond to reviews: think about your availability or that of your collaborators in the next weeks and months following a submission. Note that reviewers are volunteers, and we ask that you respect their time and effort by responding in a timely and respectful manner. +- If you use [repostatus.org badges](https://www.repostatus.org/) (which we recommend), submit when you're ready to get an _Active_ instead of _WIP_ badge. Similarly, if you use [lifecycle badges](https://www.tidyverse.org/lifecycle/), submission should happen when the package is at least _Maturing_. +- 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. + - At the submission stage, all major functions should be stable enough to be fully documented and tested; the README should make a strong case for the package. + - Your README file should strive to explain your package's functionality and aims, assuming readers have little to no domain knowledge. All technical tems, including references to other software, should be clarified. +- Your package will continue to evolve after review, the chapter on *Package evolution* [provides guidance about the topic](#evolution). + +## Preparing for Submission + +- Read and follow [our packaging style guide](#building), [reviewer's guide](#preparereview) to ensure your package meets our style and quality criteria. +- Feel free to ask any questions about the process, or your specific package, in our [Discussion Forum](https://discuss.ropensci.org). +- All submissions are automatically checked by our [pkgcheck](https://docs.ropensci.org/pkgcheck/) system to ensure packages follow our guidelines. All authors are expected to have run [the main `pkgcheck` function](https://docs.ropensci.org/pkgcheck/reference/pkgcheck.html) locally to confirm that the package is ready to be submitted. Alternatively, an even easier way to ensure a package is ready for submission is to use [the `pkgcheck` GitHub Action](https://github.com/ropensci-review-tools/pkgcheck-action) to run `pkgcheck` as a GitHub Action, as described in [our blog post](https://ropensci.org/blog/2022/02/01/pkgcheck-action/). +- If there are any aspects of `pkgcheck` which your package is unable to pass, please explain reasons in your submission template. +- If you feel your package is in scope for the + [Journal of Open-Source Software](https://joss.theoj.org/) (JOSS), 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. + +## The Submission Process + +- Software is submitted for review by [opening a new issue](https://github.com/ropensci/software-review/issues/new/choose) in the software review repository and filling out the template. +- The template begins with a section which includes several HTML-styled variables (``). These are used by our `ropensci-review-bot`, and must be left in place, with values filled between the indicated start and end points, like this: +```{bash, eval = F} +insert value here