Saltar al contenido principal

31  Taller de revisión de software por pares de rOpenSci

NotaMigración

Estás leyendo la primera edición en progreso y en castellano de este libro, basada en el currículum de formación del programa de rOpenSci.

Este capítulo está siendo migrado desde los materiales del currículum al formato del libro y puede no reflejar todavía la versión final del contenido.

Contenido pendiente de migración: ver https://github.com/ropensci-training/software-review para el repo fuente de este capítulo.

32 Introducción al taller

Sobre ustedes 🏅🇪🇸 y sobre mí 👋.

Licencia: Atribución/Reconocimiento-NoComercial 4.0 Internacional

32.1 Objetivos principales

Día 1

  • Familiarizarse con las etapas y cualidades del proceso
  • Practicar proponer software para revisión

Día 2

  • Practicar enviar software para revisión

32.2 Plan para el dia 1

  • Introducción al taller
  • Introducción al proceso de punta a punta
    • Comparación con la academia
    • Proponer y enviar software para revisión
    • {pkgcheck}
    • Código de conducta y comunicación
  • Pausa
  • Proponer software para revisión
    • Abrir un “issue”
    • Comunicación amable y constructiva
  • Preguntas y comentarios

33 Introducción al proceso de punta a punta

Sobre cómo trabajamos con software y personas

NotaComparación con la academia

¿Cómo describirías la comunicación entre autora/es y revisora/es en la academia y rOpenSci?

33.1 Proponer software para revisión 

flowchart LR
    B((1-Abrir issue))
    B --> C{2-¿Dentro del alcance?}
    C -->|No| E{3-¿Excepción?}
    C -->|Sí| D[4-Enviar]
    E -->|Sí| D
    E -->|No| G((5-Cerrar issue))

33.2 Enviar software para revisión 

flowchart LR
    B((1-Abrir issue))
    B --> C[2-Revisar]
    C --> D{3-¿Listo?}
    D -->|No| C
    D -->|Sí| E((Publicar))

33.3 {pkgcheck}: Uso en un “issue”

@ropensci-review-bot check package

Ejemplo

Comandos del bot

33.4 {pkgcheck}: Uso local

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

También vas a necesitar ejecutar pkgstats::ctags_install() en Linux, o brew install global desde la terminal en MacOS.

Uso

  paquete <- "/camino/al/paquete"
  resultados <- pkgcheck::pkgcheck(paquete)
  resultados
  
  summary(resultados)

Documentación de {pkgcheck}

33.5 Código de Conducta

  • La comunidad de rOpenSci es lo más importante.
  • Nuestro objetivo es que las revisiones sean
    • abiertas,
    • no conflictivas,
    • y con el objetivo de mejorar la calidad del software.
  • ¡Sé amable! y comportate con respeto.

Guía para quienes hacen una revisión
Guía para el equipo editorial
Código de Conducta

33.6 Comunicación amable y constructiva

Ofrecer

  • Seguridad
  • Sugerencia/Decisión
  • Seguimiento

Cómo ganar amigos e influir sobre las personas
Conversaciones Cruciales: herramientas para comunicar mejor cuando más se necesita

33.7 Comunicación amable y constructiva

De parte de una autoría:

No encontré una categoría que se ajustara perfectamente, por lo que creé una categoría nueva.

Nota¿Qué puntaje le darías a cada respuesta de la editoría (1-10)?
Respuesta 1

@editor/a:

@autor/a,
Lamentablemente nuestras categorías están pre-definidas. Esperamos ampliarlas gradualmente, pero no podemos acomodar paquetes individuales.

Respuesta 2

@editor/a:

@autor/a gracias por tu consulta. El paquete parece muy interesante pero lamentablemente está fuera del alcance de las categorías actuales de rOpenSci. Nuestras categorías están pre-definidas. Esperamos ampliarlas gradualmente, pero no podemos acomodar paquetes individuales.

Respuesta 3

@editor/a:

@autor/a gracias por tu consulta. El paquete parece muy interesante pero lamentablemente está fuera del alcance de las categorías actuales de rOpenSci. Nuestras categorías están pre-definidas. Esperamos ampliarlas gradualmente, pero no podemos acomodar paquetes individuales.

Te recomendaría revisar y publicar el paquete en el Journal of Open Source Software.

Espero que pronto podamos trabajar con vos en algún otro paquete.

Decidir el alcance y el solapamiento

34 Pausa 10’

35 Proponer software para revisión

NotaAbrir un issue para proponer software para revisión en el repositorio de práctica

Usá tu propio paquete o cualquiera de estos:

  • {agroclimatico}: Índices y Estadísticos Climáticos e Hidrológicos
  • {eph}: Encuesta Permanente de Hogares de Argentina
  • {karel}: Aprendiendo programación en R
NotaUso de IA

Recibimos varios paquetes desarrollados con IA y con un historial de commits muy corto. Para hacer frente a este desafío, JOSS requiere un historial de commits de al menos seis meses.

  • Contanos si/cómo usás IA
  • Compartí tu opinión sobre si rOpenSci debería imitar la política de JOSS.

Los proyectos desarrollados de forma privada no son elegibles hasta que exista un historial público de … al menos seis meses – JOSS

36 Preguntas y comentarios

37 Introducción al día 2

¿Qué vimos en el día 1? ¿Qué vamos a ver hoy?

37.1 Plan para el día 2

  • Repaso
  • Preparar un paquete
  • Revisar un paquete: Introducción
  • Pausa
  • Revisar un paquete: Actividad
  • Responder a una revisión
  • Preguntas y respuestas

37.2 Repaso: Proponer software

El paquete karel enseña a programar. Su objetivo está fuera del alcance de rOpenSci. Fue propuesto para revisión en 2023, durante el programa de campeones/as.

Nota¿Es correcto que haya sido revisado en rOpenSci?
  1. No porque no encaja en el alcance
  2. Sí porque aunque no encaja en el alcance es una excepción
  3. Sí porque rOpenSci no rechaza paquetes
Proponer software para revisión 

flowchart LR
    B((1-Abrir issue))
    B --> C{2-¿Dentro del alcance?}
    C -->|No| E{3-¿Excepción?}
    C -->|Sí| D[4-Enviar]
    E -->|Sí| D
    E -->|No| G((5-Cerrar issue))

37.3 Repaso: Comunicación

Nota¿Por qué preferimos la segunda respuesta?
  1. De hecho preferimos la primera porque comunica la misma decisión pero es más corta.
  2. Porque es más políticamente correcta.
  3. Porque demuestra que rOpenSci es un espacio seguro para hacer consultas, sugiere un foro alternativo, e invita futuras contribuciones.
Respuesta 1

@autor/a, Lamentablemente este paquete está fuera del alcance actual de rOpenSci.

Respuesta 2

@autor/a, Gracias por tu consulta. Tu paquete se ve muy interesante, pero lamentablemente parece no encajar en las categorías actuales de rOpenSci. Te recomendaría publicarlo en el Journal of Open Source Software, el r-multiverse u otros repositorios. Y si tenés otro paquete o querés explorar cómo contribuir de otra forma, será un gusto guiarte.

38 Enviar software para revisión

NotaPreparar un paquete

Generá, interpretá, y respondé a los resultados de {pkgcheck}

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

Usa cualquier paquete, e.g. {saperlipopette v0.1.0}

Clonálo y retrocede a 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
Ejemplo 
# 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 Revisar un paquete

NotaProponé (solo) una mejora. Usá la plantilla de revisión.

Podés usar tu paquete o alguno de estos – antes de la revisión:

{agroclimatico}: Índices y Estadísticos Climáticos e Hidrológicos 
git clone https://github.com/ropensci/agroclimatico
cd agroclimatico
git checkout -b antes d537dd20
{eph}: Encuesta Permanente de Hogares de Argentina 
git clone https://github.com/ropensci/eph
cd eph
git checkout -b antes 707cd24c
{karel}: Aprendiendo programación en R 
git clone https://github.com/ropensci/karel
cd karel
git checkout -b antes 4b057e67
Ejemplos

{eph}: Usar un estilizador de código automático (revisión - commit).

{eph}: Mostrar el output de los ejemplos en README (revisión - commit).

En la sección “Modo de uso”, por favor mostrar los resultados así se ven sin necesidad de instalar el paquete y correr el código.

{agroclimatico}: Renombrar funciones (revisión - commit).

podría plantearse un ligero cambio de nombre para evitar la confusión

{agroclimatico}: Agrupar funciones (revisión - commit).

Una sugerencia para que quede más clara la funcionalidad global del paquete es agrupar las funciones en el índice por temáticas.

{karel}: Expresar la necesidad del paquete en README (revisión - commit).

Add statement of need. The Who is Karel? section of the README hints at the need but does not describe it explicitly.

38.2 Responder a una revisión

Combina habilidades que ya practicamos.

Ejemplos de revisión y respuesta en {agroclimatico}

Revisión de @VeruGHub (revisora)

Seguridad

En primer lugar, quiero agradecer la oportunidad de revisar este paquete y espero que los comentarios sirvan para mejorar en los puntos que los autores consideren oportunos.

Sugerencia/Decisión

Creo que algunos aspectos formales de la documentación pueden ser mejorados. Para empezar, la funcionalidad del paquete no está completamente definida en la documentación (Readme) … Mejorar estas descripciones e incluir programación defensiva relativa a los argumentos (en general faltante) ayudaría mucho a los usuarios.

Respuesta de @paocorrales (autora)

Seguridad

En primer lugar, muchas gracias @pmnatural y @VeruGHub por la revisión y los comentarios.

Sugerencia/Decisión

Incorporé los comentarios y sugerencias al paquete.

Seguimiento

Espero no haberme olvidado de nada, ¡aguardo sus comentarios!

Ejemplo de oposición a una sugerencia en {eph}

Respuesta de @caropradier (autora)

Seguridad

@lidefi87 ¡gracias de nuevo por tus esfuerzos!

Sugerencia/Decisión

Respecto al nombre de las funciones, intentaría no hacer modificaciones mayores para no perturbar el flujo de trabajo de nuestros usuarios actuales (aproximadamente 30 mil personas usan el paquete y quisiera evitar generarles inconvenientes si no se trata de algo fundamental para el funcionamiento del paquete). No obstante, estoy de acuerdo con que se trata de una buena práctica, y lo tendré presente al incorporar nuevas funciones.

Responder a las preguntas del equipo de revisión

39 Preguntas y comentarios

40 ¡Gracias!

¿Querés revisar un paquete? Postulate acá

41 Recursos

Taller

Comunicación

Revisión

Blogs sobre el proceso de revisión

Paquetes de campeones/as en español

Ofrecerte como voluntario/a para revisar