Taller de revisión de software por pares de rOpenSci

Autor/a

Mauro Lepore

Fecha de publicación

25 de noviembre de 2025

Introducción al taller

Sobre ustedes 🏅🇪🇸 y sobre mí 👋.

_{Licencia: Atribución/Reconocimiento-NoComercial 4.0 Internacional}

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

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 respuestas

Introducción al proceso de punta a punta

Sobre cómo trabajamos con software y personas

Comparación con la academia

En la academia y en rOpenSci:

¿Cuál es la motivación de un/a autor/a o revisor/a?
¿Qué otros roles participan?
¿Cuándo se acepta o rechaza un trabajo?
¿En qué plataforma se intercambian comentarios?
¿Cómo es la comunicación esperada?

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))

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))

{pkgcheck}: Uso en un “issue”

@ropensci-review-bot check package

Ejemplo

Comandos del bot

{pkgcheck}: Uso local

Instalación

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

Ejemplo

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

Documentación de {pkgcheck}

Código de Conducta

La comunidad es nuestro mejor activo
Nuestra diversidad es nuestra fortaleza
No toleramos ningún tipo de acoso

Código de Conducta

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

Comunicación amable y constructiva

Explica cómo y por qué el paquete encaja en estas categorías.

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

Del 1 al 10, cuántos puntos le das a cada respuesta?

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.

_{Responder a las presentaciones fuera del ámbito de aplicación}

Pausa 10’

Proponer software para revisión

Abrir un “issue”

Abrí 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

Comunicación amable y constructiva

{karel} está fuera del alcance de las categorías de rOpenSci (fue revisado como excepción por el programa de campeones/as)
Asumí el rol de editor/a
Escribí un comentario amable y constructivo, notificando al autor que el paquete está fuera del alcance de rOpenSci
Recomendá revisarlo y publicarlo en el “Journal of Open Source Education”

Preguntas y respuestas

Generá preguntas sobre el proceso de proponer software para revisión. Para inspirarte podés explorar:
- la plantilla real de propuesta de software para revisión
- “issues” reales etiquetados con 0/presubmission
Votá con + en 3 preguntas de otras personas
Respuestas

Introducción al día 2

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

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

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.

¿Es correcto que haya sido revisado en rOpenSci?

No porque no encaja en el alcance
Sí porque aunque no encaja en el alcance es una excepción
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))

Repaso: Comunicación

¿Por qué preferimos la segunda respuesta?

De hecho preferimos la primera porque comunica la misma decisión pero es más corta.
Porque es más políticamente correcta.
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.

Enviar software para revisión

Preparar un paquete

Genera, interpreta, y responde a 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}

Clonálo

git clone https://github.com/ropensci-training/saperlipopette
cd saperlipopette

# pak::pak()
out <- pkgcheck::pkgcheck()
summary(out)

out

Mejoras

# install.packages("codemetar")
# install.packages("usethis")

# Has a 'codemeta.json' file
codemetar::write_codemeta()

# Has a 'contributing' file
usethis::use_tidy_contributing()

# Package has at least one HTML vignette
usethis::use_article("saperlipopette")

# All functions have examples
#' @examples
#' path <- withr::local_tempdir()
#' create_all_exercises(path)

# R CMD check found 1 error
usethis::use_package("parserdate")

Revisar un paquete

Propone (solo) una mejora. Usa 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.

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 de quienes revisan}

Preguntas

¡Gracias!

¿Querés revisar un paquete? Postulate acá

Recursos

Taller

Comunicación

Código de Conducta

Revisión

Blogs sobre el proceso de revisión

Paquetes de campeones/as en español

Ofrecerte como voluntario/a para revisar