Configurar integración continua usando GitHub Actions

Documentación Guías para desarrolladores
,
1

:mag: Visión general

Para construir una extensión robusta para Discourse, puede ser aconsejable incluir la Integración Continua (CI) en tu plugin o componente de tema. Esto ayudará a detectar errores desde el principio y reducirá las posibilidades de errores en tu código.

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

:gear: Configuración

Para agregar flujos de trabajo automatizados para GitHub Actions que detecten problemas, 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 ‘flujos de trabajo reutilizables’ aquí.

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

Alternativamente, si ya tienes un proyecto al que deseas agregar los flujos de trabajo, simplemente copia el flujo de trabajo relevante en 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 mayor específica de nuestros flujos de trabajo reutilizables. Las pequeñas mejoras que hagamos en los flujos de trabajo se aplicarán automáticamente en tu tema/plugin. Para cambios que rompen la compatibilidad (por ejemplo, la introducción de un nuevo linter), incrementaremos la versión mayor de los flujos de trabajo reutilizables y deberás actualizar tu flujo de trabajo para que apunte a la nueva versión.

:tada: ¡Voilà! ¡Todo está configurado! Simplemente, crea un commit o un PR en tu repositorio y GitHub Actions detectará automáticamente los flujos de trabajo y comenzará a ejecutar las tareas.

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

Si una prueba falla, hacer clic en los detalles te dará alguna información sobre lo que falló, lo cual puede darte pistas sobre qué está mal en tu código y qué necesita ser corregido.

Ver ejemplo

ejemplo de falla
ejemplo de falla2192×1018 250 KB

:white_check_mark: Agrega tus propias pruebas

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

Para obtener detalles sobre cómo escribir pruebas 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 algunos 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 tiene control de versiones: sugiere cambios en GitHub.

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