Configurar la integración continua con GitHub Actions

Documentación Guías para desarrolladores
,
1

:mag: Resumen

Para crear una extensión robusta para Discourse, puede ser conveniente incluir la Integración Continua (CI) en tu plugin o componente de tema. Esto ayudará a detectar errores a tiempo y reducirá la probabilidad de que haya errores en tu código.

Configurar un flujo de trabajo de CI utilizando GitHub Actions para automatizar las compilaciones 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 agregar flujos de trabajo automatizados de GitHub actions para la detección, debes 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 la revisión de código (linting) y las pruebas.

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

En el repositorio de la plantilla, en GitHub puedes 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 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 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 en tu tema/plugin. Para los cambios incompatibles (por ejemplo, la introducción de un nuevo linter), aumentaremos la versión principal de los flujos de trabajo reutilizables, y necesitarás actualizar tu flujo de trabajo para que apunte a la nueva versión.

:tada: ¡Listo! Ya lo tienes 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 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ó, hacer clic en los detalles te dará alguna información sobre qué falló, lo que podría darte pistas sobre qué hay mal en tu código y qué necesita ser corregido.

Ver ejemplo

example failure
example failure2192×1018 250 KB

:white_check_mark: Añade 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 de front-end con EmberJS, consulta:

Para obtener 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 está bajo 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