Mettre en place l'intégration continue avec GitHub Actions

Documentation Guides pour les développeurs
,
1

:mag: Vue d’ensemble

Pour créer une extension robuste pour Discourse, il peut être judicieux d’intégrer l’Intégration Continue (CI) à votre plugin ou composant de thème. Cela aidera à détecter les erreurs tôt et réduira les chances de bugs dans votre code.

La mise en place d’un flux de travail CI à l’aide de GitHub Actions pour automatiser les builds et les tests est une approche utilisée par l’équipe Discourse pour tous nos composants, et nous vous recommandons de faire de même.

:gear: Mise en place

Pour ajouter des flux de travail automatisés pour GitHub actions afin de détecter les problèmes, 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 GitHub actions devra exécuter. Par exemple, il pourrait s’agir de fichiers .yml pour le linting et les tests.

Nous avons créé des modèles de flux de travail pour les plugins et les composants de thème que vous pouvez utiliser. 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 Utiliser ce modèle 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 automatiquement effet dans votre thème/plugin. Pour les modifications cassantes (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: Et voilà ! Tout est en place ! Il suffit de créer un commit ou une PR vers votre dépôt et GitHub actions détectera automatiquement les flux de travail et commencera à exécuter les tâches.

GitHub actions affichera un détail de chaque test et, après son exécution, indiquera soit :white_check_mark: ou :x: selon que le test a réussi ou échoué.

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

Voir un 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 manière d’écrire des tests front-end avec EmberJS, voir :

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

: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 sous contrôle de 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 »