Configurazione dell'Integrazione Continua usando GitHub Actions

[Discourse]

Panoramica

Per creare un’estensione robusta per Discourse, è consigliabile includere l’Integrazione Continua (CI) nel tuo plugin o componente tema. Questo aiuterà a rilevare gli errori precocemente e a ridurre le possibilità di bug nel tuo codice.

L’impostazione di un flusso di lavoro di GitHub Actions per automatizzare build e test è un approccio che il team di Discourse utilizza su tutti i nostri componenti, e ti consigliamo di fare lo stesso.

Impostazione

Per aggiungere flussi di lavoro automatizzati che GitHub Actions possa rilevare, devi creare una cartella .github/workflows nella directory principale del tuo repository.

All’interno della cartella workflows puoi definire una serie di automazioni che GitHub Actions dovrà eseguire. Ad esempio, questi potrebbero essere file .yml per il linting e i test.

Abbiamo creato flussi di lavoro modello sia per i plugin che per i componenti tema che puoi utilizzare. Questi si collegano alle nostre definizioni di “flusso di lavoro riutilizzabile” qui.

Nel repository scheletro del modello, su GitHub puoi fare clic sul pulsante Use this template per creare un repository di plugin/componente tema basato sul modello.

In alternativa, se hai già un progetto a cui desideri aggiungere i flussi di lavoro, copia semplicemente il flusso di lavoro pertinente nella cartella .github/workflows/ del tuo repository:

Plugin: discourse-plugin.yml

Temi e Componenti Tema: discourse-theme.yml

Questi modelli sono bloccati a una specifica versione principale dei nostri flussi di lavoro riutilizzabili. Piccoli miglioramenti che apportiamo ai flussi di lavoro verranno automaticamente applicati al tuo tema/plugin. Per modifiche che rompono la compatibilità (ad esempio, l’introduzione di un nuovo linter), aumenteremo la versione principale dei flussi di lavoro riutilizzabili e dovrai aggiornare il tuo flusso di lavoro per puntare alla nuova versione.

Ecco fatto! Sei pronto! Crea semplicemente un commit o una PR al tuo repository e GitHub Actions rileverà automaticamente i flussi di lavoro e inizierà a eseguire i job.

GitHub Actions mostrerà una ripartizione di ogni test e, dopo l’esecuzione, indicherà o a seconda che il test sia superato o fallito.

Se un test è fallito, facendo clic sui dettagli otterrai alcune informazioni su ciò che è fallito, il che potrebbe darti indizi su cosa non va nel tuo codice e cosa deve essere corretto.

Vedi esempio

Aggiungi i tuoi test

Affinché i test dei plugin e dei componenti funzionino efficacemente, è importante che tu scriva test per il tuo plugin o componente tema.

Per i dettagli su come scrivere test front-end con EmberJS, consulta:

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

Per maggiori dettagli sulla scrittura di test RSpec con Rails, consulta:

• RSpec - Behavior Driven Development for Ruby

Esempi

A tuo vantaggio, abbiamo selezionato un paio di esempi di plugin e componenti tema che hanno integrati test robusti:

Plugin / Componente	Test Lato Client	Test Lato Server
Assign	Visualizza Cartella	Visualizza Cartella
Calendar	Visualizza Cartella	Visualizza Cartella
Reactions	Visualizza Cartella	Visualizza Cartella
Right Sidebar Blocks	Visualizza Cartella
Tag Icons	Visualizza Cartella
Table Builder	Visualizza Cartella

---

Questo documento è controllato tramite versione - suggerisci modifiche su github.

[pfaffman (Jay Pfaffman)]

Potresti menzionare esplicitamente GitHub - discourse/discourse-theme-skeleton: Template for Discourse themes e notare che dovresti seguirlo per prendere nota delle modifiche a quei file.

[Simon_Manning]

@pfaffman

dovresti guardarlo per prendere nota delle modifiche in quei file

Speriamo che i flussi di lavoro riutilizzabili possano essere uniti, rendendo questa parte meno rilevante poiché i nuovi repository creati dal modello utilizzeranno direttamente i flussi di lavoro dal repository del modello.

[keegan (Keegan George)]

Grazie @pfaffman e @Simon_Manning, ottimi spunti. Ho aggiornato l’OP di conseguenza.

[david (David Taylor)]

Ho aggiornato l’OP per includere le istruzioni per l’utilizzo dei nostri nuovi “workflow riutilizzabili”. Le modifiche minori che apportiamo alle definizioni dei workflow possono ora essere applicate automaticamente ai tuoi temi/plugin senza alcun lavoro manuale.

Abbiamo creato workflow di template sia per plugin che per componenti tema che puoi utilizzare. Questi si collegano alle nostre definizioni di ‘workflow riutilizzabili’ qui.

…

Plugin: discourse-plugin.yml

Temi e Componenti Tema: discourse-theme.yml

\u003e Questi template sono bloccati a una specifica versione principale dei nostri workflow riutilizzabili. I piccoli miglioramenti che apportiamo ai workflow avranno effetto automatico nel tuo tema/plugin. Per modifiche che rompono la compatibilità (ad es. introducendo un nuovo linter), aumenteremo la versione principale dei workflow riutilizzabili e dovrai aggiornare il tuo workflow per puntare alla nuova versione.

[merefield (Robert)]

Devo fare qualcosa di speciale per avere un plugin testato contro gli ultimi test superati e stabile?

[Simon_Manning]

Il flusso di lavoro scheletro plugin utilizza quanto segue, che penso testerà contro il branch predefinito, quindi main. Il flusso di lavoro riutilizzabile ha un input opzionale core_ref e per quanto ne so, senza di esso verrà effettuato il checkout del branch predefinito del repository discourse/discourse.

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

Non posso dire se ciò limiti effettivamente il test a main o meno, ma se lo fa, potresti aggiungere una strategia di matrice per eseguire una volta per ogni ref contro cui vuoi testare.

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)]

Sì, dovrebbe funzionare. Oppure puoi semplicemente scrivere manualmente i due job senza usare una matrice:

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 notare, tuttavia: questi job non controlleranno .discourse-compatiblity. Quindi vale la pena farlo solo per i plugin che non utilizzano quel file e devono essere compatibili contemporaneamente sia con main che con stable.

Per tutti i temi/plugin pubblici di CDCK, aggiungiamo una voce a discourse-compatibility per “congelarli” ad ogni rilascio stabile. Quindi non dobbiamo preoccuparci della compatibilità stabile mentre li sviluppiamo.

[merefield (Robert)]

Grazie a entrambi.

@david

Per tutti i temi/plugin pubblici di CDCK, aggiungiamo una voce a discourse-compatibility per ‘bloccarli’ ad ogni rilascio stabile.

Sì, questo è probabilmente l’approccio più diretto. L’unico svantaggio è che potenzialmente trattiene funzionalità (e nuove correzioni di bug)