Configuration de l'intégration continue avec GitHub Actions

Documentation Guides pour les développeurs
,
1

:mag: Aperçu

Pour créer une extension robuste pour Discourse, il est judicieux d’inclure l’Intégration Continue (IC) dans votre plugin ou composant de thème. Cela aidera à détecter les erreurs tôt et à réduire les chances de bogues dans votre code.

La configuration d’un flux de travail d’IC utilisant GitHub Actions pour automatiser les constructions et les tests est une approche que l’équipe Discourse utilise sur tous nos composants, et nous vous recommandons de faire de même.

:gear: Configuration

Pour ajouter des flux de travail automatisés pour la détection par les actions GitHub, vous devez créer un dossier .github/workflows dans le répertoire racine de votre dépôt.

À l’intérieur du dossier workflows, vous pouvez définir un ensemble d’automatisations que les actions GitHub devront exécuter. Par exemple, il pourrait s’agir de fichiers .yml pour le lintage et les tests.

Nous avons créé des modèles de flux de travail pour les plugins et les composants de thème dont vous pouvez vous servir. Ceux-ci se connectent à nos définitions de « flux de travail réutilisables » ici.

Dans le dépôt squelette du modèle, sur GitHub, vous pouvez cliquer sur le bouton Use this template pour créer un dépôt de plugin/composant de thème basé sur le modèle.

Alternativement, si vous avez déjà un projet auquel vous souhaitez ajouter les flux de travail, copiez simplement le flux de travail pertinent dans le dossier .github/workflows/ de votre dépôt :

:electric_plug: Plugins : discourse-plugin.yml

:jigsaw: Thèmes et Composants de Thème : discourse-theme.yml

:point_up: Ces modèles sont verrouillés sur une version majeure spécifique de nos flux de travail réutilisables. Les petites améliorations que nous apportons aux flux de travail prendront effet automatiquement dans votre thème/plugin. Pour les changements majeurs (par exemple, l’introduction d’un nouveau linter), nous augmenterons la version majeure des flux de travail réutilisables, et vous devrez mettre à jour votre flux de travail pour pointer vers la nouvelle version.

:tada: Voilà ! Vous êtes prêt ! Créez simplement un commit ou une PR vers votre dépôt et les actions GitHub détecteront automatiquement les flux de travail et commenceront à exécuter les tâches.

Les actions GitHub afficheront une ventilation de chaque test et, après l’exécution, indiqueront soit :white_check_mark: soit :x: selon que le test a réussi ou échoué.

Si un test a échoué, cliquer sur les détails vous donnera des informations sur ce qui a échoué, ce qui pourrait vous donner des indices sur ce qui ne va pas avec votre code et ce qui doit être corrigé.

Voir l'exemple

example failure
example failure2192×1018 250 KB

:white_check_mark: Ajoutez vos propres tests

Pour que les tests de plugins et de composants fonctionnent efficacement, il est important que vous écriviez des tests pour votre plugin ou composant de thème.

Pour plus de détails sur la façon d’écrire des tests front-end avec EmberJS, consultez :

Pour plus de détails sur l’écriture de tests RSpec avec Rails, consultez :

:bulb: Exemples

Pour votre bénéfice, nous avons sélectionné quelques exemples de plugins et de composants de thème qui intègrent des tests robustes :

Plugin / Composant Tests Côté Client Tests Côté Serveur
Assign :link: Voir le Dossier :link: Voir le Dossier
Calendar :link: Voir le Dossier :link: Voir le Dossier
Reactions :link: Voir le Dossier :link: Voir le Dossier
Right Sidebar Blocks :link: Voir le Dossier
Tag Icons :link: Voir le Dossier
Table Builder :link: Voir le Dossier

Ce document est contrôlé par version - suggérez des modifications sur github.

15 « J'aime »
How could a CI workflow for unofficial plugins be implemented?
Unexpected error in Discourse Plugin CI
6

Vous pourriez mentionner explicitement GitHub - discourse/discourse-theme-skeleton: Template for Discourse themes et noter que vous devriez le surveiller pour prendre note des changements dans ces fichiers.

4 « J'aime »
7

J’espère que les workflows réutilisables pourront être fusionnés, rendant cette partie moins pertinente car les nouveaux dépôts créés à partir du modèle utiliseront directement les workflows du dépôt modèle.

2 « J'aime »
8

Merci @pfaffman et @Simon_Manning, bonnes remarques. J’ai mis à jour le message d’origine en conséquence.

4 « J'aime »
9

J’ai mis à jour l’OP pour inclure des instructions sur l’utilisation de nos nouveaux « workflows réutilisables ». Les modifications mineures que nous apportons aux définitions de workflow peuvent désormais être appliquées automatiquement à vos thèmes/plugins sans aucun travail manuel.

3 « J'aime »
10

Dois-je faire quelque chose de spécial pour qu’un plugin soit testé contre les derniers tests réussis et stable ?

1 « J'aime »
11

Le workflow de squelette de plugin utilise ce qui suit, ce qui, je pense, testera par rapport à la branche par défaut, donc main. Le workflow réutilisable a une entrée optionnelle core_ref et d’après ce que je peux comprendre, sans elle, la branche par défaut du dépôt discourse/discourse sera extraite.

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

Je ne peux pas dire si cela le limite réellement aux tests par rapport à main ou non, mais si c’est le cas, vous pourriez ajouter une stratégie de matrice pour exécuter une fois pour chaque ref que vous souhaitez tester.

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

Oui, cela devrait fonctionner. Ou vous pouvez simplement écrire les deux jobs manuellement sans utiliser de 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

Il est à noter cependant : ces jobs ne vérifieront pas le fichier .discourse-compatiblity. Il n’est donc pertinent de le faire que pour les plugins qui n’utilisent pas ce fichier et qui doivent être compatibles simultanément avec main et stable.

Pour tous les thèmes/plugins publics de CDCK, nous ajoutons une entrée à discourse-compatibility pour les « figer » à chaque version stable. Ainsi, nous n’avons pas à nous soucier de la compatibilité avec la version stable lors de leur développement.

5 « J'aime »
13

Merci à vous deux.

Oui, c’est probablement l’approche la plus simple. Le seul inconvénient est qu’elle peut potentiellement retarder des fonctionnalités (et de nouvelles corrections de bugs).

2 « J'aime »