Configurer l'intégration continue avec GitHub Actions

[Discourse]

Aperçu

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 permettra de détecter les erreurs dès le début et de réduire les risques de bugs dans votre code.

Configurer un flux de travail d’[abbr title=“Intégration Continue”]CI[/abbr] en utilisant GitHub Actions pour automatiser les builds et les tests est une approche adoptée par l’équipe Discourse pour tous nos composants, et nous vous recommandons de faire de même.

Configuration

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 peut 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. Ces flux de travail sont connectés à 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.

Sinon, si vous avez déjà un projet auquel vous souhaitez ajouter des 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 s’appliqueront automatiquement à 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.

Voilà ! Tout est prêt ! Il vous suffit de créer un commit ou une [abbr title=“Demande de tirage”]PR[/abbr] 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 exécution, indiquera soit un soit une , selon que le test a réussi ou échoué.

Si un test échoue, 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

Ajouter vos propres tests

Pour que les tests des plugins et des composants fonctionnent efficacement, il est important que vous écriviez des tests pour votre plugin ou votre 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 l’écriture de tests RSpec avec Rails, consultez :

• RSpec - Développement piloté par le comportement pour Ruby

Exemples

Pour votre confort, 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 versionné - proposez 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).