Configurar Integração Contínua usando GitHub Actions

[Discourse]

Visão geral

Para criar uma extensão robusta para o Discourse, pode ser sábio incluir Integração Contínua (CI) no seu plugin ou componente de tema. Isso ajudará a detectar erros precocemente e reduzirá as chances de bugs no seu código.

Configurar um fluxo de trabalho de CI usando GitHub Actions para automatizar builds e testes é uma abordagem que a equipe do Discourse utiliza em todos os nossos componentes, e recomendamos que você faça o mesmo.

Configuração

Para adicionar fluxos de trabalho automatizados para detecção via GitHub Actions, você precisa criar uma pasta .github/workflows no diretório raiz do seu repositório.

Dentro da pasta workflows, você pode definir um conjunto de automações que o GitHub Actions precisará executar. Por exemplo, esses podem ser arquivos .yml para linting e testes.

Criamos fluxos de trabalho de modelo tanto para plugins quanto para componentes de tema, que você pode utilizar. Esses se conectam às nossas definições de ‘fluxo de trabalho reutilizável’ aqui.

No repositório de modelo do esqueleto, no GitHub, você pode clicar no botão Usar este modelo para criar um repositório de plugin/componente de tema baseado no modelo.

Alternativamente, se você já tem um projeto ao qual deseja adicionar os fluxos de trabalho, basta copiar o fluxo de trabalho relevante para a pasta .github/workflows/ do seu repositório:

Plugins: discourse-plugin.yml

Temas e Componentes de Tema: discourse-theme.yml

Esses modelos estão vinculados a uma versão principal específica dos nossos fluxos de trabalho reutilizáveis. Pequenas melhorias que fazemos nos fluxos de trabalho terão efeito automático no seu tema/plugin. Para mudanças que quebram a compatibilidade (por exemplo, introduzindo um novo linter), aumentaremos a versão principal dos fluxos de trabalho reutilizáveis, e você precisará atualizar seu fluxo de trabalho para apontar para a nova versão.

Voilà! Tudo pronto! Basta criar um commit ou um PR para o seu repositório e o GitHub Actions detectará automaticamente os fluxos de trabalho e começará a executar os jobs.

O GitHub Actions exibirá um resumo de cada teste e, após a execução, indicará um ou dependendo se o teste foi aprovado ou reprovado.

Se um teste falhar, clicar nos detalhes fornecerá algumas informações sobre o que falhou, o que pode dar pistas sobre o que está errado no seu código e o que precisa ser corrigido.

Ver exemplo

Adicione seus próprios testes

Para que os testes de plugins e componentes funcionem de forma eficaz, é importante que você escreva testes para o seu plugin ou componente de tema.

Para detalhes sobre como escrever testes de front-end com EmberJS, veja:

• Write acceptance tests and component tests for Ember code in Discourse
• Introduction - Testing - Ember Guides

Para mais detalhes sobre a escrita de testes RSpec com Rails, veja:

• RSpec - Behavior Driven Development for Ruby

Exemplos

Para seu benefício, selecionamos alguns exemplos de plugins e componentes de tema que possuem testes robustos integrados:

Plugin / Componente	Testes no Lado do Cliente	Testes no Lado do Servidor
Assign	Ver Pasta	Ver Pasta
Calendar	Ver Pasta	Ver Pasta
Reactions	Ver Pasta	Ver Pasta
Right Sidebar Blocks	Ver Pasta
Tag Icons	Ver Pasta
Table Builder	Ver Pasta

---

Este documento é controlado por versão - sugira alterações no github.

[pfaffman (Jay Pfaffman)]

Você pode mencionar explicitamente GitHub - discourse/discourse-theme-skeleton: Template for Discourse themes e observar que você deve acompanhá-lo para tomar nota das alterações nesses arquivos.

[Simon_Manning]

@pfaffman

você deve assisti-lo para observar as alterações nesses arquivos

Espero que os fluxos de trabalho reutilizáveis possam ser mesclados, tornando esta parte menos relevante, pois novos repositórios feitos a partir do modelo usarão os fluxos de trabalho diretamente do repositório do modelo.

[keegan (Keegan George)]

Obrigado @pfaffman e @Simon_Manning, bons pontos. Atualizei o OP de acordo.

[david (David Taylor)]

Atualizei o OP para incluir instruções para usar nossos novos ‘fluxos de trabalho reutilizáveis’. Pequenas alterações que fazemos nas definições do fluxo de trabalho agora podem ser aplicadas automaticamente aos seus temas/plugins sem nenhum trabalho manual.

Criamos fluxos de trabalho de modelo tanto para plugins quanto para componentes de tema que você pode utilizar. Estes se conectam às nossas definições de ‘fluxo de trabalho reutilizável’ aqui.

…

Plugins: discourse-plugin.yml

Temas e Componentes de Tema: discourse-theme.yml

\u003e Esses modelos estão bloqueados para uma versão principal específica de nossos fluxos de trabalho reutilizáveis. Pequenas melhorias que fazemos nos fluxos de trabalho terão efeito automático em seu tema/plugin. Para alterações drásticas (por exemplo, introdução de um novo linter), aumentaremos a versão principal dos fluxos de trabalho reutilizáveis, e você precisará atualizar seu fluxo de trabalho para apontar para a nova versão.

[merefield (Robert)]

Preciso fazer algo especial para que um plugin seja testado contra os testes mais recentes e que estejam passados e estáveis?

[Simon_Manning]

O fluxo de trabalho de esqueleto de plugin usa o seguinte, que acho que testará contra o branch padrão, então main. O fluxo de trabalho reutilizável tem uma entrada opcional core_ref e, pelo que pude apurar, sem ela, o branch padrão do repositório discourse/discourse será verificado.

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

Não posso dizer se isso realmente o limita a testar contra main ou não, mas se sim, você pode adicionar uma estratégia de matriz para executar uma vez para cada ref contra a qual deseja testar.

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

[david (David Taylor)]

Sim, isso deve resolver. Ou você pode simplesmente escrever os dois trabalhos manualmente sem usar uma 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 notar, no entanto: esses trabalhos não verificarão .discourse-compatiblity. Portanto, isso só vale a pena fazer em plugins que não usam esse arquivo e precisam ser compatíveis com main e stable simultaneamente.

Para todos os temas/plugins públicos da CDCK, adicionamos uma entrada ao discourse-compatibility para ‘congelá-los’ em cada lançamento estável. Assim, não precisamos nos preocupar com a compatibilidade estável enquanto os desenvolvemos.

[merefield (Robert)]

Obrigado a ambos.

@david

Para todos os temas/plugins públicos do CDCK, adicionamos uma entrada ao discourse-compatibility para ‘congelá-los’ em cada lançamento estável.

Sim, essa é provavelmente a abordagem mais direta. A única desvantagem é que potencialmente atrasa recursos (e novas correções de bugs)