Configurare l'integrazione continua con GitHub Actions

[Discourse]

Panoramica

Per creare un’estensione robusta per Discourse, può essere saggio includere l’Integrazione Continua (CI) nel tuo plugin o componente di tema. Questo aiuterà a rilevare gli errori in anticipo e ridurrà la probabilità di bug nel tuo codice.

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

Configurazione

Per aggiungere flussi di lavoro automatizzati per GitHub Actions, è necessario 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 trattarsi di file .yml per linting e test.

Abbiamo creato flussi di lavoro modello sia per i plugin che per i componenti di 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/componente di 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 di Tema: discourse-theme.yml

Questi modelli sono vincolati a una specifica versione principale dei nostri flussi di lavoro riutilizzabili. I piccoli miglioramenti che apportiamo ai flussi di lavoro avranno effetto automatico nel tuo tema/plugin. Per le modifiche di rottura (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! Basta creare 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à un riepilogo di ogni test e, dopo l’esecuzione, indicherà un o un a seconda che il test sia riuscito o fallito.

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

Vedi esempio

Aggiungi i tuoi test

Perché i test dei plugin e dei componenti funzionino efficacemente, è importante che tu scriva test per il tuo plugin o componente di 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 ulteriori dettagli sulla scrittura di test RSpec con Rails, consulta:

• RSpec - Behavior Driven Development for Ruby

Esempi

Per tua comodità, abbiamo selezionato alcuni esempi di plugin e componenti di tema che hanno 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 è sottoposto a controllo delle versioni - 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)