Configurar Integración Continua usando GitHub Actions

Documentación Guías para desarrolladores
,
1

:mag: Visión general

Para crear una extensión robusta para Discourse, es aconsejable incluir la Integración Continua (CI) en tu componente de plugin o tema. Esto ayudará a detectar errores de forma temprana y a reducir las posibilidades de errores en tu código.

Configurar un flujo de trabajo de CI utilizando GitHub Actions para automatizar la compilación y las pruebas es un enfoque que el equipo de Discourse utiliza en todos nuestros componentes, y te recomendamos que hagas lo mismo.

:gear: Configuración

Para añadir flujos de trabajo automatizados para que GitHub Actions los detecte, necesitas crear una carpeta .github/workflows en el directorio raíz de tu repositorio.

Dentro de la carpeta workflows puedes definir un conjunto de automatizaciones que GitHub Actions necesitará ejecutar. Por ejemplo, estos podrían ser archivos .yml para linting y pruebas.

Hemos creado flujos de trabajo de plantilla tanto para plugins como para componentes de tema que puedes utilizar. Estos se conectan a nuestras definiciones de ‘flujo de trabajo reutilizable’ aquí.

En el repositorio de la plantilla, en GitHub puedes hacer clic en el botón Usar esta plantilla para crear un repositorio de plugin/componente de tema basado en la plantilla.

Alternativamente, si ya tienes un proyecto al que te gustaría añadir los flujos de trabajo, simplemente copia el flujo de trabajo relevante a la carpeta .github/workflows/ de tu repositorio:

:electric_plug: Plugins: discourse-plugin.yml

:jigsaw: Temas y Componentes de Tema: discourse-theme.yml

:point_up: Estas plantillas están bloqueadas a una versión principal específica de nuestros flujos de trabajo reutilizables. Las pequeñas mejoras que hagamos en los flujos de trabajo se reflejarán automáticamente en tu tema/plugin. Para cambios disruptivos (por ejemplo, introducir un nuevo linter), incrementaremos la versión principal de los flujos de trabajo reutilizables y deberás actualizar tu flujo de trabajo para que apunte a la nueva versión.

:tada: ¡Listo! ¡Ya está todo configurado! Simplemente, crea un commit o una PR en tu repositorio y GitHub Actions detectará automáticamente los flujos de trabajo y comenzará a ejecutar los trabajos.

GitHub Actions mostrará un desglose de cada prueba y, después de ejecutarla, indicará un :white_check_mark: o un :x: dependiendo de si la prueba pasó o falló.

Si una prueba falló, al hacer clic en los detalles obtendrás información sobre lo que falló, lo que puede darte pistas sobre lo que está mal en tu código y lo que necesita ser arreglado.

Ver ejemplo

ejemplo de fallo
ejemplo de fallo2192×1018 250 KB

:white_check_mark: Añade tus propias pruebas

Para que las pruebas de plugins y componentes funcionen eficazmente, es importante que escribas pruebas para tu plugin o componente de tema.

Para más detalles sobre cómo escribir pruebas de front-end con EmberJS, consulta:

Para más detalles sobre cómo escribir pruebas RSpec con Rails, consulta:

:bulb: Ejemplos

Para tu beneficio, hemos seleccionado un par de ejemplos de plugins y componentes de tema que tienen pruebas robustas integradas:

Plugin / Component Pruebas del lado del cliente Pruebas del lado del servidor
Assign :link: Ver Carpeta :link: Ver Carpeta
Calendar :link: Ver Carpeta :link: Ver Carpeta
Reactions :link: Ver Carpeta :link: Ver Carpeta
Right Sidebar Blocks :link: Ver Carpeta
Tag Icons :link: Ver Carpeta
Table Builder :link: Ver Carpeta

Este documento está controlado por versiones - sugiere cambios en github.

15 Me gusta
6

Podrías mencionar explícitamente GitHub - discourse/discourse-theme-skeleton: Template for Discourse themes y señalar que deberías seguirlo para tomar nota de los cambios en esos archivos.

4 Me gusta
7

Esperemos que los flujos de trabajo reutilizables puedan fusionarse, haciendo que esta parte sea menos relevante ya que los nuevos repositorios creados a partir de la plantilla utilizarán los flujos de trabajo directamente desde el repositorio de la plantilla.

2 Me gusta
8

Gracias @pfaffman y @Simon_Manning, buenos puntos. He actualizado el OP en consecuencia.

4 Me gusta
9

He actualizado el OP para incluir instrucciones para usar nuestros nuevos ‘flujos de trabajo reutilizables’. Los pequeños ajustes que hagamos en las definiciones de los flujos de trabajo ahora se pueden aplicar automáticamente a sus temas/plugins sin ningún trabajo manual.

3 Me gusta
10

¿Necesito hacer algo especial para que un plugin sea probado con las últimas pruebas pasadas y estable?

1 me gusta
11

El flujo de trabajo de esqueleto de plugin utiliza lo siguiente, que creo que se probará contra la rama predeterminada, es decir, main. El flujo de trabajo reutilizable tiene una entrada opcional core_ref y, por lo que puedo entender, sin ella se extraerá la rama predeterminada del repositorio discourse/discourse.

jobs:
  ci:
    uses: discourse/.github/.github/workflows/discourse-plugin.yml@v1

No puedo decir si eso lo limita realmente a probar contra main o no, pero si lo hace, podrías agregar una estrategia de matriz para ejecutar una vez por cada ref contra la que quieras probar.

jobs:
  ci:
    strategy:
      matrix:
        target: [tests-passed, stable]
    uses: discourse/.github/.github/workflows/discourse-plugin.yml@v1
    with:
      core_ref: ${{ matrix.target }}
3 Me gusta
12

Sí, eso debería funcionar. O puedes simplemente escribir los dos trabajos manualmente sin usar una matriz:

name: Discourse Plugin

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  ci:
    uses: discourse/.github/.github/workflows/discourse-plugin.yml@v1

  ci-stable:
    uses: discourse/.github/.github/workflows/discourse-plugin.yml@v1
    with:
      core_ref: stable

Vale la pena señalar: estos trabajos no comprobarán .discourse-compatiblity. Por lo tanto, esto solo vale la pena hacerlo en complementos que no usan ese archivo y necesitan ser compatibles con main y stable simultáneamente.

Para todos los temas/complementos públicos de CDCK, agregamos una entrada a discourse-compatibility para ‘congelarlos’ en cada versión estable. Luego, no necesitamos preocuparnos por la compatibilidad estable mientras los desarrollamos.

5 Me gusta
13

Gracias a ambos.

Sí, ese es probablemente el enfoque más sencillo. La única desventaja es que potencialmente retrasa las características (y las nuevas correcciones de errores).

2 Me gusta