Configurer l'intégration continue en utilisant GitHub Actions

[Discourse]

Vue d’ensemble

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

La mise en place d’un flux de travail d’intégration continue (CI) à l’aide de GitHub Actions pour automatiser les builds et les tests est une approche que l’équipe Discourse utilise sur tous nos composants, et nous vous recommandons de faire de même.

Mise en place

Pour ajouter des flux de travail automatisés que GitHub Actions pourra détecter, 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 flux de travail modèles 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 :

Plugins : discourse-plugin.yml

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

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 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 qu’il pointe vers la nouvelle version.

Voilà ! Vous êtes prêt ! Créez simplement un commit ou une demande de tirage (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 une ventilation de chaque test et, après l’exécution, indiquera soit soit 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 peut vous donner des indices sur ce qui ne va pas dans votre code et ce qui doit être corrigé.

Voir l'exemple

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 :

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

Pour plus de détails sur la façon d’écrire des tests RSpec avec Rails, consultez :

• RSpec - Behavior Driven Development for Ruby

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	Voir le dossier	Voir le dossier
Calendar	Voir le dossier	Voir le dossier
Reactions	Voir le dossier	Voir le dossier
Right Sidebar Blocks	Voir le dossier
Tag Icons	Voir le dossier
Table Builder	Voir le dossier

---

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

[pfaffman (Jay Pfaffman)]

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.

[Simon_Manning]

@pfaffman

vous devriez le regarder pour prendre note des changements dans ces fichiers

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.

[keegan (Keegan George)]

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

[david (David Taylor)]

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.

Nous avons créé des workflows modèles pour les plugins et les composants de thème que vous pouvez utiliser. Ceux-ci se connectent à nos définitions de « workflow réutilisable » ici.

…

Plugins : discourse-plugin.yml

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

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

[merefield (Robert)]

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

[Simon_Manning]

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 }}

[david (David Taylor)]

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.

[merefield (Robert)]

Merci à vous deux.

@david

Pour tous les thèmes/plugins publics de CDCK, nous ajoutons une entrée à discourse-compatibility pour les « figer » à chaque version stable.

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