Configuración de Integración Continua usando GitHub Actions

Documentación Guías para desarrolladores
,
1

:mag: Resumen

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

Configurar un flujo de trabajo de GitHub Actions para automatizar compilaciones y pruebas es un enfoque que el equipo de Discourse utiliza en todos nuestros componentes, y recomendamos que usted haga lo mismo.

:gear: Configuración

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

Dentro de la carpeta workflows, puede 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 puede utilizar. Estos se conectan a nuestras definiciones de ‘flujo de trabajo reutilizable’ aquí.

En el repositorio esqueleto de la plantilla, en GitHub puede hacer clic en el botón Use this template para crear un repositorio de plugin/componente de tema basado en la plantilla.

Alternativamente, si ya tiene un proyecto al que desea añadir los flujos de trabajo, simplemente copie el flujo de trabajo relevante a la carpeta .github/workflows/ de su repositorio:

:electric_plug: Plugins: discourse-plugin.yml

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

:point_up: Estas plantillas están fijadas 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 aplicarán automáticamente a su tema/plugin. Para cambios disruptivos (ej. introducir un nuevo linter), aumentaremos la versión principal de los flujos de trabajo reutilizables, y usted deberá actualizar su flujo de trabajo para que apunte a la nueva versión.

:tada: ¡Listo! ¡Ya está todo configurado! Simplemente, cree un commit o un PR a su 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 :x: dependiendo de si la prueba pasó o falló.

Si una prueba falló, hacer clic en los detalles le proporcionará información sobre lo que falló, lo que puede darle pistas sobre lo que está mal en su código y lo que necesita ser arreglado.

Ver ejemplo

example failure
example failure2192×1018 250 KB

:white_check_mark: Añadir sus propias pruebas

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

Para obtener detalles sobre cómo escribir pruebas de front-end con EmberJS, consulte:

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

:bulb: Ejemplos

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

Plugin / Componente 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: sugiera cambios en github.

← START DOCS ASSET MAP
[
{
“local_path”: “/assets/ci-with-github-actions-1.png”,
“local_sha1”: “c3fb59eeb13645670b751959d13cdf8e423e0fcf”,
“remote_short_url”: “upload://imziUfvg1AloA7IQ5jXMyn85Ngu.png”
}
]
END DOCS ASSET MAP →

15 Me gusta
How could a CI workflow for unofficial plugins be implemented?
Unexpected error in Discourse Plugin CI
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