Saltar al contenido principal

31  rOpenSci Software Peer Review Workshop

NotaBeing refined

You are reading the first edition in progress and in English of this book, based on the training curriculum of the rOpenSci Champions Program. This chapter should be readable, but it is undergoing final polishing.

Source of the migrated content: this chapter originates from the software-review repository.

32 Workshop Introduction

About you 🏅🌐 and about me 👋.

License: Attribution-NonCommercial 4.0 International

32.1 Main Objectives

Day 1

  • Familiarize yourself with the stages and qualities of the process
  • Practice proposing software for review

Day 2

  • Practice submitting software for review

32.2 Day 1 Plan

  • Workshop introduction
  • End-to-end process introduction
    • Comparison with academia
    • Proposing and submitting software for review
    • {pkgcheck}
    • Code of conduct and communication
  • Break
  • Proposing software for review
    • Opening an issue
    • Kind and constructive communication
  • Questions and comments

33 Review Process Overview

About how we work with software and people

NotaComparison with Academia

How would you describe the communication between authors and reviewers in academia and rOpenSci?

33.1 Proposing Software for Review 

flowchart LR
    B((1-Open issue))
    B --> C{2-In scope?}
    C -->|No| E{3-Exception?}
    C -->|Yes| D[4-Submit]
    E -->|Yes| D
    E -->|No| G((5-Close issue))

33.2 Submitting Software for Review 

flowchart LR
    B((1-Open issue))
    B --> C[2-Review]
    C --> D{3-Ready?}
    D -->|No| C
    D -->|Yes| E((Publish))

33.3 {pkgcheck}: Usage in an Issue

@ropensci-review-bot check package

Example

Bot commands

33.4 {pkgcheck}: Local Usage

NotaInstallation 
  options (repos = c (
    ropenscireviewtools = "https://ropensci-review-tools.r-universe.dev",
    CRAN = "https://cloud.r-project.org"
  ))
  install.packages("pkgcheck")

Also you’ll need to run pkgstats::ctags_install() on Linux, or brew install global from the terminal on MacOS.

Usage

  package <- "/path/to/package"
  results <- pkgcheck::pkgcheck(package)
  results

  summary(results)

{pkgcheck} documentation

33.5 Code of Conduct

  • rOpenSci’s community is our best asset.
  • We aim for reviews to be
    • open,
    • non-adversarial,
    • and focused on improving software quality.
  • Be respectful and kind.

Guide for reviewers
Guide for editors
Code of Conduct

33.6 Kind and Constructive Communication

Offer

  • Safety
  • Suggestion/Decision
  • Follow-up

How to Win Friends and Influence People Crucial Conversations: Tools for Talking When Stakes Are High

33.7 Kind and Constructive Communication

From an author:

I couldn’t find a category that fit perfectly, so I created a new category.

NotaHow would you score each response from an editor (1-10)?
Response 1

@editor:

@author, Unfortunately our categories are pre-defined. We hope to expand them gradually, but we cannot accommodate individual packages.

Response 2

@editor:

@author, thank you for your inquiry. The package looks very interesting but unfortunately it’s outside the scope of rOpenSci’s current categories. Our categories are pre-defined. We hope to expand them gradually, but we cannot accommodate individual packages.

Response 3

@editor:

@author, thank you for your inquiry. The package looks very interesting but unfortunately it’s outside the scope of rOpenSci’s current categories. Our categories are pre-defined. We hope to expand them gradually, but we cannot accommodate individual packages.

I would recommend reviewing and publishing the package in the Journal of Open Source Software.

I hope we can work with you on another package soon.

Deciding on scope and overlap

34 Break 10’

35 Proposing Software for Review

NotaOpen an issue to propose software for review in the practice repository

Use your own package or any of these:

  • {agroclimatico}: Climate and Hydrological Indices and Statistics
  • {eph}: Argentina’s Permanent Household Survey Data and Manipulation Utilities
  • {karel}: Learning programming with Karel the robot
NotaUse of AI

We received several packages developed with AI and with a very short commit history. To face this challenge, JOSS requires a commit history of at least six months.

  • Tell us if/how you use AI
  • Share your opinion on whether rOpenSci should imitate JOSS policy.

Projects developed privately are not eligible until there is a public record of open development: at least six months – JOSS

36 Questions and Comments

37 Day 2 Introduction

What did we see on day 1? What are we going to see today?

37.1 Day 2 Plan

  • Review
  • Preparing a package
  • Reviewing a package: Introduction
  • Break
  • Reviewing a package: Activity
  • Responding to a review
  • Questions and answers

37.2 Review: Proposing Software

The karel package teaches programming. Its objective is outside the scope of rOpenSci. It was proposed for review in 2023, during the champions program.

NotaWas it correct for it to have been reviewed at rOpenSci?
  1. No because it doesn’t fit the scope
  2. Yes because although it doesn’t fit the scope it’s an exception
  3. Yes because rOpenSci doesn’t reject packages
Proposing software for review 

flowchart LR
    B((1-Open issue))
    B --> C{2-In scope?}
    C -->|No| E{3-Exception?}
    C -->|Yes| D[4-Submit]
    E -->|Yes| D
    E -->|No| G((5-Close issue))

37.3 Review: Communication

NotaWhy do we prefer the second response?
  1. Actually we prefer the first one because it communicates the same decision but is shorter.
  2. Because it’s more politically correct.
  3. Because it demonstrates that rOpenSci is a safe space to make inquiries, suggests an alternative forum, and invites future contributions.
Response 1

@author, Unfortunately this package is outside rOpenSci’s current scope.

Response 2

@author, Thank you for your inquiry. Your package looks very interesting, but unfortunately it doesn’t seem to fit rOpenSci’s current categories. I would recommend publishing it in the Journal of Open Source Software, the r-multiverse or other repositories. And if you have another package or want to explore how to contribute in other ways, we’ll be happy to guide you.

38 Submitting Software for Review

NotaPreparing a Package

Generate, interpret, and respond to {pkgcheck} results

Installation 
  options (repos = c (
    ropenscireviewtools = "https://ropensci-review-tools.r-universe.dev",
    CRAN = "https://cloud.r-project.org"
  ))
  install.packages("pkgcheck")

Use any package, e.g. {saperlipopette v0.1.0}

Clone it and checkout v0.1.0 
git clone https://github.com/ropensci-training/saperlipopette
cd saperlipopette
git checkout v0.1.0
# pak::pak()
out <- pkgcheck::pkgcheck()
summary(out)

out
Example 
# install.packages("usethis")

# ✖ does not have a 'contributing' file.
usethis::use_tidy_contributing()

# ✖ Package has no HTML vignettes
usethis::use_article("saperlipopette")

# ✖ These functions do not have examples: [create_all_exercises].
# From https://github.com/ropensci-training/saperlipopette/blob/main/R/create-all.R
#' @examplesIf interactive()
#' parent_path <- withr::local_tempdir()
#' path <- create_all_exercises(parent_path = parent_path)
#
# devtools::document()

38.1 Reviewing a Package

NotaPropose (only) one improvement. Use the review template.

You can use your package or any of these – before the review:

{agroclimatico}: Climate and Hydrological Indices and Statistics 
git clone https://github.com/ropensci/agroclimatico
cd agroclimatico
git checkout -b antes d537dd20
{eph}: Argentina’s Permanent Household Survey Data and Manipulation Utilities 
git clone https://github.com/ropensci/eph
cd eph
git checkout -b antes 707cd24c
{karel}: Learning programming with Karel the robot 
git clone https://github.com/ropensci/karel
cd karel
git checkout -b antes 4b057e67
Examples

{eph}: Use an automatic code formatter (review - commit).

Please use an automatic code formatter (e.g., usethis::use_tidy_style()). It’s useful to see that the style is consistent and follows a popular style guide like the “tidyverse style guide” (https://style.tidyverse.org/). This helps avoid thinking about style and saves mental energy for noticing more important things. Here are some examples of style violations:

{eph}: Show the output of examples in README (review - commit).

In the “Usage” section, please show the results so they can be seen without needing to install the package and run the code.