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))
Taller de revisión de software por pares de rOpenSci
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 comentarios
Introducción al proceso de punta a punta
Sobre cómo trabajamos con software y personas
Proponer software para revisión
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{pkgcheck}: Uso local
Uso
paquete <- "/camino/al/paquete"
resultados <- pkgcheck::pkgcheck(paquete)
resultados
summary(resultados)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.
Comunicación amable y constructiva
Ofrecer
- Seguridad
- Sugerencia/Decisión
- Seguimiento
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.
Pausa 10’
Proponer software para revisión
Preguntas y comentarios
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.
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
Enviar software para revisión
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()Revisar un paquete
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.
Preguntas y comentarios
¡Gracias!
¿Querés revisar un paquete? Postulate acá
Recursos
Taller
Comunicación
Revisión
- Propone o enviá software para revisión
- Guía de desarrollo standard y estadistico
- Categorías de paquetes standard y estadistico
- Para quienes crean paquetes
- Para quienes hacen una revisión
- Guía de software estadístico
- pkgcheck
- pkgmatch (ejemplo)
- Plantilla de revisión
- r-multiverse
Blogs sobre el proceso de revisión
- Revisión del software, perspectivas de un académico
- Experiencias revisando paquetes de rOpenSci por primera vez
- Así que (no) crees que puedas revisar un paquete
Paquetes de campeones/as en español