Configura la Continuous Integration con GitHub Actions

[Discourse]

Panoramica

Per creare un’estensione robusta per Discourse, può essere utile integrare l’Integrazione Continua (CI) nel tuo plugin o componente del tema. Questo aiuterà a rilevare gli errori in fase iniziale e ridurrà le probabilità di bug nel tuo codice.

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

Configurazione

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

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

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

Nel repository modello, su GitHub, puoi fare clic sul pulsante Usa questo modello per creare un repository di plugin o componente del 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 del Tema: discourse-theme.yml

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

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

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

Se un test fallisce, cliccando sui dettagli otterrai alcune informazioni su cosa è fallito, che potrebbero fornirti indizi su cosa non va nel tuo codice e cosa deve essere corretto.

Vedi esempio

Aggiungi i tuoi test

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

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

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

Per ulteriori dettagli sulla scrittura di test RSpec con Rails, vedi:

• RSpec - Behavior Driven Development for Ruby

Esempi

Per tua comodità, abbiamo selezionato alcuni esempi di plugin e componenti del tema che dispongono di test robusti integrati:

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