Este capítulo explica qué es la integración continua (CI, por sus siglas en inglés) y luego resume nuestras recomendaciones sobre cómo usarla.
Junto con el capítulo anterior, forma parte de nuestras directrices para la revisión por pares de software.
La integración continua ejecuta tests sobre el software automáticamente. En el caso de rOpenSci, CI significa, en la práctica, que un conjunto de test se ejecutará automáticamente a través de GitHub, cada vez que hagas un commit o pull request a GitHub.
La CI automatiza la ejecución de tests globales de los paquetes, como R CMD check (ver tests). Es posible configurar la CI antes de escribir tus tests, entonces CI los ejecutará a medida que los envíes al repositorio.
Todos los paquetes de rOpenSci deben utilizar alguna forma de integración continua. Esto asegura que todos los commits, pull requests y nuevas branches pasan por R CMD check. Los resultados de todos los tests se muestran en la página del pull request en GitHub, lo cual proporciona información sobre los problemas y proteje de aceptar cambios que rompan tu paquete. La integración continua de los paquetes de rOpenSci también debe estar vinculada a un servicio de cobertura de código que indique cuántas líneas son chequeadas por los tests unitarios.
Tanto el estado de los tests como el porcentaje de cobertura del código deben informarse mediante etiquetas en el README de tu paquete.
Los paquetes de R deben tener CI para todos los sistemas operativos (Linux, Mac OSX, Windows) si contienen:
Código compilado
Dependencias de Java
Dependencias de otros lenguajes
Paquetes con llamadas al sistema
Procesamiento de texto, por ejemplo obtener nombres de personas (para encontrar problemas de codificación).
Cualquier cosa que incluya llamadas al sistema de archivos / rutas de acceso.
Ante la duda de si estos criterios se aplican a tu paquete, es mejor añadir CI para todos los sistemas operativos. La mayoría de los servicios de CI para paquetes de R lo permiten sin mucha complicación utilizando la configuración estándar.
Existen muchos servicios de integración continua. Algunos son servicios independientes (CircleCI, AppVeyor), mientras que otros están integrados a servicios de alojamiento del código o relacionados (GitHub Actions, GitLab, AWS Code Pipeline). Distintos servicios permiten distintas configuraciones de sistemas operativos.
GitHub Actions es una opción conveniente para quienes desarrollan paquetes de R y ya utilizan GitHub, ya que está integrado en la plataforma y es compatible con todos los sistemas operativos necesarios.
Hay acciones compatibles con el ecosistema R así como soporte de primera clase con el paquete usethis. Todos los paquetes enviados a rOpenSci para su revisión por pares son comprobados por nuestro propio sistema, pkgcheck, el cual se describe con más detalle en la Guía de autoría. Estos tests también están disponibles como acción de GitHub en el repositorio ropensci-review-tools/pkgcheck-action. Es recomendable utilizar esta acción para confirmar que el paquete pasa todos los tests antes de enviarlo. Consulta nuestro blog para más información.
El paquete usethis se puede usar con otros sistemas de CI, aunque estas funciones están siendo deprecadas. rOpenSci también provee el paquete circle, el cual ayuda a configurar cadenas de CircleCI, y el paquete tic para la construcción de cadenas de CI más complicadas.
Requerimos que los paquetes de rOpenSci no sólo se testeen usando la versión más reciente de R, sino también con la anterior y con la versión en desarrollo. Esto garantiza compatibilidad con R base, tanto con versiones futuras como con versiones pasadas.
Los detalles de cómo ejecutar tests utilizando diferentes versiones de R localmente se pueden encontrar en la viñeta de R-hub sobre la ejecución de Checks locales en Linux con Docker.
Puedes definir los detalles de los checks para cada una de las versiones utilizando una matriz de tests.
Si desarrollas un paquete que depende o está destinado para Bioconductor, puede que el paquete biocthis te resulte relevante.
Puedes utilizar estos consejos para minimizar los tiempos de construcción en CI:
Puede que encuentres útil el post de Hugo Gruson Dependencias del sistema en paquetes de R y pruebas automáticas.
Recomendamos dejar de utilizar Travis.
Para la integración continua en Windows, consulta R + AppVeyor. Configúralo con usethis::use_appveyor().
Aquí tienes consejos para minimizar el tiempo de compilación de AppVeyor:
Guarda los paquetes instalados en una caché. Mira, por ejemplo, este archivo de configuración. AppVeyor usará la caché automáticamente si lo configuras con usethis::use_appveyor().
Activa los rolling builds.
Ya no transferimos los proyectos de AppVeyor a la cuenta de AppVeyor de rOpenSci, así que después de transferir tu repo a la organización de GitHub “ropensci”, la etiqueta será [](https://ci.appveyor.com/project/individualaccount/pkgname).
Circle CI es utilizado, por ejemplo, por el paquete de rOpenSci bomrang como servicio de integración continua.
La integración continua también debe incluir información sobre la cobertura de los tests a través de un servicio de testing como Codecov o Coveralls.
Recomendamos utilizar Codecov. Para activar Codecov para tu repo, ejecuta usethis::use_github_action("test-coverage"), el cual crea un archivo .github/workflows/test-coverage.yaml. También tienes que dar acceso a Codecov a tu repositorio de GitHub, ver la guía de inicio rápido de Codecov (en inglés) para saber cómo hacerlo. Luego añade una etiqueta de estado de Codecov en la parte superior de tu README.md, puedes consultar Status Badges (etiquetas de estado) en la documentación de Codecov.
Actualmente, Codecov tiene acceso a todos los repositorios de GitHub de la organización ropensci por defecto. Cuando tu repositorio sea aceptado y transferido a ropensci, el acceso de Codecov debería transferirse automáticamente. Tendrás que actualizar la URL de la etiqueta para que apunte al repositorio alojado en ropensci.
Para más detalles, consulta el README del paquete covr, así como la documentación de usethis::use_coverage() y usethis::use_github_action().
Si ejecutas la cobertura en varios servicios de CI los resultados se unirán.
Después de transferir el repo a la organización GitHub “ropensci” de rOpenSci, cada push se chequeará en OpenCPU y la persona que hace el commit recibirá una notificación por correo electrónico. Este es un servicio adicional de CI para que permite correr funciones en paquetes de R de forma remota a través de https://ropensci.ocpu.io/ utilizando la API de opencpu. Para más detalles sobre este servicio, consulta la página de ayuda de OpenCPU que también indica dónde hacer preguntas.
Después de la transferencia a la organización GitHub “ropensci” de rOpenSci, cada push al repo de GitHub disparará la construcción (o actualización) del sitio web de tu paquete usando pkgdown. Puedes encontrar el estado de este proceso en la URL https://ropensci.r-universe.dev/ui#packages y en el estado del commit. El sitio web estará en https://docs.ropensci.org/package_name (por ejemplo para magick). Si tu paquete tiene un archivo de configuración de pkgdown, rOpenSci docs lo usará para crear el sitio web, excepto para el tema, que se utilizará rotemplate paquete.
Por favor, informa sobre errores, haz preguntas y solicita nuevas funcionalidades sobre este servicio y sobre la plantilla en https://github.com/ropensci-org/rotemplate/.