La siguiente documentación hace referencia a un pipeline que busca realizar la compilación de Codelabs y su despliegue en un sitio estático usando tags y categorías para su organización en subconjuntos/subsitios. El pipeline cuenta con una aplicación que permite realizar la compilación de los Codelabs usando la herramienta claat y la URL de un Google Doc (más específicamente su llave de identificación) que sigue las convenciones de estilo de un Codelab. Luego de la compilación, los archivos resultantes son enviados a un repositorio mediante una petición de cambios (pull request/PR) para, luego de su aceptación, desplegar el sitio con los nuevos codelabs.

Así pues, dentro de este flujo de trabajo, dos pasos son manuales y el resto de acciones son automáticas. La primera acción, es enviar el requerimiento de compilación de un Codelab al usar la aplicación de compilación ingresando un identificador de un documento de Google. La segunda acción es la aceptación de la petición de cambios que se efectúa en el repositorio que contiene el código del sitio estático.

En la siguiente sección, se realiza una descripción más en detalle de cada uno de los pasos así como condiciones para poder realizar el uso del mismo y la compilación de los codelabs.

Algunos enlaces asociados a los elementos previamente mencionados:

• Código de la aplicación de compilación de Codelabs se encuentra disponible en Github
• Código del sitio estático se encuentra disponible en Github
• Dirección del sitio desplegado

Teniendo en cuenta la necesidad de aceptación de la petición de cambios en Github, y la necesidad de dar permiso para el acceso de la herramienta al Google Doc fuente del Codelab, es necesario que el autor del Codelab realice una petición a MISO Virtual de dos permisos:

1. Acceso para poder aceptar peticiones de cambios en el repositorio de Github que contiene el sitio estático utilizado para alojar los codelabs.
2. Acceso a una carpeta en Google Drive en la cuenta de MISO Virtual para el guardado de el documento fuente del Codelab o en su defecto dar acceso de al menos lectura a la cuenta de google de MISO Virtual sobre el Google Doc (se prefiere el uso de la primera opción para realizar un mejor manejo de las fuentes).

Los pasos mencionados anteriormente, y que componen la compilación de los codelabs, se resumen en el siguiente gráfico (se dejan por fuera las acciones asociadas a la petición de permisos o acceso a Google Drive o el repositorio usado para el despliegue de los Codelabs):

Dentro del diagrama se muestran las acciones realizadas dentro de pipeline y se especifica si es una acción iniciada por una persona () o si se hace automáticamente ().

Archivo fuente

El Google Doc fuente debe seguir las convenciones de estilo que se detallan en el siguiente enlace: https://github.com/googlecodelabs/tools/blob/master/FORMAT-GUIDE.md

Páginas de agrupación de codelabs

El sitio donde se alojan los codelabs permite agrupar codelabs usando los metadatos tag y category. Actualmente los siguientes agrupaciones (con una subpágina asociada) existen:

Para agregar un Codelab a una de las categorías existentes basta con agregar dentro de la tabla de metadatos del mismo el tag de identificación listado anteriormente. Por ejemplo, para agregar un Codelab al subsitio del curso GIT basta con agregar la palabra git al campo correspondiente a los tags y categoría (en caso de que la fila no exista, la misma debe ser creada dando como nombre de campo el nombre en inglés):

Compilación y creación de petición para agregarlo al sitio estático

Luego de la obtención de permisos tanto al repositorio en Github del sitio estático de codelabs y la creación de un Google Doc con los permisos adecuados respecto a la cuenta de Google de MISO Virtual, es posible realizar la petición inicial de compilación del documento a un Codelab. Para esto basta con dirigirse al siguiente enlace y proporcionar la URL del documento.

Al realizar la petición, como se menciona en el diagrama de flujo de trabajo, se realizará:

• Compilación del documento de Google Docs a un Codelab.
• Apertura de una petición de cambio agregando el Codelab (nuevo o la actualización de uno existente) al repositorio en Github del sitio estático.

Igualmente, si el proceso es exitoso la aplicación realizará una redirección a una vista previa del Codelab compilado:

En caso contrario, una pantalla de error se mostrará indicando algunas recomendaciones de posibles causas del fallo:

NOTA: La creación de la petición de cambios puede tomar un tiempo dependiendo de la cantidad de elementos que el codelab contenga.

Luego de haber realizado la compilación del Google Doc, se generará una petición de cambios en el repositorio del sitio estático de Codelabs. La petición se realiza en una rama que tiene como nombre la URL seleccionada para el Codelab (por ejemplo para este documento es doc-codelabs-builder) abriéndose como tal la pull request:

Dentro de la petición de cambios (pull request) se puede previsualizar una versión del sitio de codelabs desplegado en Netlify (asociado la comprobación deploy-preview):

Finalmente, si el nuevo codelab es correcto (contenido, metadata, URL, etc) y se tienen los permisos adecuados sobre el repositorio, es necesario aceptar la petición de cambios (aprobar y agregar el label ready a la petición o dar emerger manualmente a la misma usando la interfaz de GitHub usando la opción de Squash and Merge preferiblemente):

Aprobar y agregar el label ‘ready'

Emerger usando las opciones de GitHub directamente

Posteriormente, al hacer merge de la petición el sitio estático de Codelabs se actualizará con la nueva versión del sitio incluyendo el nuevo Codelab (se puede observar la actualización del sitio estático con Github Actions al actualizarse la rama master en la pestaña Actions del repositorio):