CI/CD: Conservación de Islas / Ciencia de Datos

Colabora usando LaTeX y GitHub

18 May 2021 - Evaristo y Nepo

Seguramente usas LaTeX por alguna de las razones siguientes:

Esas son las razones por las cuales mis colegas y yo nos iniciamos en LaTeX cuando trabajábamos de manera individual. Sin embargo, en GECI usamos LaTeX para elaborar los reportes de nuestros análisis de datos porque LaTeX también permite el trabajo colaborativo.

Los documentos escritos en LaTeX tienen una característica muy poderosa: están escritos en texto simple. La principal ventaja de escribir un documento en texto simple es que podemos poner el documento bajo control de versiones de código fuente y así forjar el documento de manera colaborativa. La plataforma más popular de desarrollo colaborativo es GitHub.

¿Qué es GitHub?

GitHub es una plataforma de alojamiento de código para el control de versiones y la colaboración. Nos permite trabajar con otras personas juntos en proyectos desde cualquier lugar.

¿Cómo puedo usar GitHub para colaborar con otros?

Un pull request (PR) es la unidad fundamental de colaboración en GitHub. Es mediante un PR que sugieres cambios en el documento de otra persona. En un PR hay dos roles: quien contribuye y quien revisa. En esta nota nos enfocaremos en la perspectiva de la persona que contribuye. El ciclo de vida de un PR es abrir una rama, consignar los cambios en nuestro escrito, solicitar revisión mediante un PR, atender las correcciones solicitadas y cerrar la rama incorporando los cambios a la rama principal. Ahora veamos este ciclo a más detalle.

Abrir una rama

Para iniciar nuestra contribución primero creamos una nueva rama temporal. Cuando creamos una rama temporal es como si hiciéramos una copia de nuestra carpeta de trabajo original (a la que llamamos rama principal). Las ramas podrían representar el trabajo en diferentes secciones de nuestro escrito, por ejemplo una rama por cada capítulo. También nuestras ramas podrían tener las diferentes revisiones o ediciones de nuestros colaboradores.

Consignar los cambios

Los cambios que hacemos en una rama los guardamos en consignaciones. Con cada consignación que hacemos, la rama temporal va divergiendo de la rama principal. Cuando terminamos de trabajar en una sección, pedimos a las personas con las colaboramos que revisen los cambios.

Solicitar revisión

Para solicitar revisión creamos un PR. En los PR de GitHub encontramos herramientas para que las revisiones que recibamos sean más claras. Cada PR solo nos muestra las secciones que hemos modificado, comparando la versión anterior con la actual. La persona que revisa nuestros cambios puede agregar observaciones o sugerir una mejora en cada línea de nuestro escrito. Al final de una tanda de revisión, quien revisa nuestro PR solicitará que hagamos cambios.

Atender correcciones

Una vez que recibimos una revisión, consignamos los cambios solicitados en la misma rama temporal con la que creamos el PR. Cuando terminamos de atender las correcciones solicitadas pedimos una segunda tanda de revisión. Este ciclo: solicitar revisión y atender correcciones, lo repetimos las veces necesarias. Eventualmente, la persona que revisa nos aceptará el PR.

Cerrar la rama

Una vez que nos han aceptado el PR es hora de cerrar la rama mediante un merge. El merge lo que hace es incorporar a nuestra rama principal todos los cambios que hicimos en la rama temporal. Finalmente, borramos la rama temporal.

Ejemplo

Esta nota fue revisada en este PR. En este caso, @nepito es el revisor y @evaristor es el contribuidor. La primer tanda de revisión la puedes ver aquí.

Conclusión

Los documentos en LaTeX están escritos en texto simple lo que nos permite usar GitHub para trabajar de manera colaborativa. En GitHub, un PR es el medio por el cual solicitamos que revisen nuestra contribución para que sea incorporada al documento original.