Configurare l'Integrazione Continua usando GitHub Actions

Documentazione Guide per sviluppatori
,
1

:mag: Panoramica

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

L’impostazione di un flusso di lavoro di CI utilizzando 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.

:gear: 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 tematici che puoi utilizzare. Questi si collegano alle nostre definizioni di “flusso di lavoro riutilizzabile” qui.

Nel repository modello del template, su GitHub puoi fare clic sul pulsante Usa questo modello per creare un repository di plugin/componente tematico 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:

:electric_plug: Plugin: discourse-plugin.yml

:jigsaw: Temi e Componenti Tematici: discourse-theme.yml

:point_up: Questi modelli sono bloccati a una specifica versione principale dei nostri flussi di lavoro riutilizzabili. Piccoli miglioramenti che apportiamo ai flussi di lavoro avranno effetto automatico nel tuo tema/plugin. Per modifiche che introducono incompatibilità (ad es. introducendo 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.

:tada: Fatto! Sei pronto! Semplicemente, crea un commit o una richiesta di pull (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à un :white_check_mark: o un :x: a seconda che il test sia passato o fallito.

Se un test è fallito, facendo clic sui dettagli otterrai alcune informazioni su cosa è fallito, il che potrebbe darti indizi su cosa c’è di sbagliato nel tuo codice e cosa deve essere corretto.

Vedi esempio

example failure
example failure2192×1018 250 KB

:white_check_mark: Aggiungi i tuoi test

Affinché i test dei plugin e dei componenti funzionino in modo efficace, è importante che tu scriva test per il tuo plugin o componente tematico.

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

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

:bulb: Esempi

A tuo beneficio, abbiamo selezionato un paio di esempi di plugin e componenti tematici che hanno integrato test robusti:

Plugin / Componente Test lato client Test lato server
Assign :link: Visualizza cartella :link: Visualizza cartella
Calendar :link: Visualizza cartella :link: Visualizza cartella
Reactions :link: Visualizza cartella :link: Visualizza cartella
Right Sidebar Blocks :link: Visualizza cartella
Tag Icons :link: Visualizza cartella
Table Builder :link: Visualizza cartella

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

15 Mi Piace
6

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.

4 Mi Piace
7

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.

2 Mi Piace
8

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

4 Mi Piace
9

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.

3 Mi Piace
10

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

1 Mi Piace
11

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 }}
3 Mi Piace
12

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.

5 Mi Piace
13

Grazie a entrambi.

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

2 Mi Piace