Modèles de workflow

Ce document explique comment mettre en place des workflows d'intégration continue (CI) pour un parcours de langage Exercism à l'aide de GitHub Actions (GHA). Il fournit des bonnes pratiques et des exemples que tu peux utiliser pour créer tes propres workflows CI rapides, fiables et robustes. Les workflows GHA de ce dossier peuvent être adaptés à n'importe quel système de CI, car la structure de base reste la même.

Il permet de :

  • Décrire le workflow CI idéal
  • Examiner les points de vigilance et les recommandations
  • Te fournir quelques modèles à utiliser
  • Te laisser un guide pour migrer depuis Travis

Un exemple d'implémentation de ces fichiers de workflow se trouve dans exercism/javascript.

AU SECOURS : ça a l'air de demander beaucoup de travail 😓

Le reste du document est conçu pour expliquer comment fonctionnent les workflows. Si tu es pressé et que tu veux simplement passer de Travis ou Circle à GHA sans optimiser les scripts de PR, jette un œil à notre guide de ~10 minutes sur Migrer depuis Travis.

Actions CI d'un parcours

Voici les actions recommandées pour vérifier l'intégrité du contenu de ton dépôt :

  1. le lint de configlet afin de vérifier config.json
  2. vérifier les stubs
  3. vérifier la documentation (v3 exige de nouveaux fichiers ; cela pourrait être déplacé vers configlet)
  4. lancer le lint sur les exercices avec une configuration « mainteneurs »
  5. tester les exercices à l'aide des fichiers d'exemple/exemplar (cela peut inclure une étape de compilation)

Il peut aussi y avoir des actions propres au parcours. Par exemple :

  1. vérifier l'intégrité des configurations des exercices
  2. vérifier le formatage des fichiers d'exercice

Et tu voudras peut-être des vérifications supplémentaires pour te faciliter la vie, comme :

  1. s'assurer que CONTRIBUTING existe
  2. s'assurer qu'il existe un lockfile raisonnable pour les dépendances
  3. s'assurer que les liens dans les fichiers Markdown sont valides
  4. ...

Recommandations

Fréquence d'exécution des vérifications

Pour chaque action, demande-toi à quelle fréquence elle doit s'exécuter.

  • Le lint de configlet est si important (un parcours peut casser si le config.json casse) qu'il devrait sans doute toujours s'exécuter, mais il n'a besoin de s'exécuter qu'une fois par commit.
  • La vérification de l'existence ou de l'intégrité des fichiers n'a besoin de s'exécuter qu'une fois par commit.
  • Si un parcours est censé fonctionner avec plusieurs versions de runtime ou de compilateur, la compilation et les tests des exercices doivent être exécutés pour chaque version prise en charge.
  • Les PRs n'ont probablement besoin d'exécuter des actions que sur les fichiers ajoutés ou modifiés, mais comme un fichier peut influencer un exercice, il est plus sûr d'exécuter les actions pour l'exercice concerné si l'un de ses fichiers change.

Il peut être très utile de rendre les actions qui doivent s'exécuter disponibles aussi en local. Cela signifie que les scripts qui font le vrai travail peuvent également être lancés à la main. Pour y parvenir, ne mets pas l'action en ligne dans les fichiers de workflow, mais crée un script autonome. Par exemple, la vérification des stubs peut être entièrement écrite en Bash dans le fichier de workflow, mais la recommandation ici est plutôt de créer un nouveau script exécutable scripts/ci-check.

« Mais la commande est très courte, par exemple eslint . --ext ts --ext tsx. »

Quand cette commande doit être mise à jour, il faut désormais la mettre à jour partout dans la documentation, dans les fichiers de workflow et dans l'esprit des mainteneurs. L'extraire dans un script règle tout cela. Lire un fichier de workflow peut aussi être très intimidant.

Vérifications sur les PRs qui modifient des exercices

Les scripts scripts/pr et scripts/pr-check (voir les modèles) sont exécutés avec plusieurs arguments, un pour chaque fichier modifié ou ajouté dans cette PR. Par exemple, si two-fer a été mis à jour, un appel peut ressembler à ceci :

scripts/pr exercises/two-fer/README.md exercises/two-fer/.meta/example.ext

Il est recommandé d'exécuter les actions sur l'exercice modifié et non sur le fichier modifié. En effet, modifier un fichier déclenche probablement des changements pour tout l'exercice (pense à la configuration, aux paquets).

Pas encore prêt ? / Trop complexe ?

Avant de mettre en place cette optimisation, tu peux l'ignorer sans problème ! Le guide de migration suggère de l'ajouter à une étape ultérieure. Si les arguments d'entrée sont ignorés, toutes les vérifications s'exécuteront sur tous les exercices. Ce n'est pas un problème. Cela prendra simplement plus de temps.

Vérifications d'intégrité

Si le parcours a un seul fichier de dépendances « de premier niveau » et/ou d'autres fichiers de configuration, ajoute une étape d'intégrité (qui existe aux côtés d'un scripts/sync ou bin/sync, lequel copierait tous les fichiers de configuration vers tous les exercices) qui vérifie que les fichiers de premier niveau et de base sont les mêmes que celui copié dans les répertoires des exercices. Ainsi, les dépendances peuvent être mises à jour, synchronisées dans tout le dépôt, et on peut s'assurer que tous les exercices ont la même configuration.

Une façon courante d'y parvenir est d'utiliser une somme de contrôle. Ubuntu (et diverses autres distributions Linux) est livré avec un outil appelé sha1sum, mais n'importe quelle méthode permettant de hacher ou de réduire le fichier de configuration (md5, sha1, crc32) en une somme de contrôle fonctionnerait :

$ sha1sum README.md
cd58091c5043bf21f00d39ff1740d8b2976deeff *README.md

Vérifications de sécurité

Si le parcours utilise des workflows supplémentaires qui nécessitent l'accès au jeton GitHub ou à d'autres secrets, il est recommandé d'épingler toutes les actions utilisées dans le workflow à un commit précis. Voir le guide de renforcement de la sécurité de GitHub pour plus de détails.

Par exemple :

- uses: julia-actions/setup-julia@v1
+ uses: julia-actions/setup-julia@d26d1111976eae5f00db04f0515ab744ec9cd79e # 1.3.1

Si l'outillage utilise des lockfiles pour gérer les dépendances, pense à les ajouter au dépôt et à utiliser un « lockfile figé » dans les fichiers de workflow. Par exemple : npm ci, yarn install --frozen-lockfile et bundle install --frozen. Cela garantit que le lockfile est à jour lorsque tu modifies les dépendances et empêche l'introduction de paquets malveillants.

Modèles

Dans ce dossier, il y a au minimum les modèles suivants :

  • configlet.yml : ce workflow récupère le dernier binaire configlet et lance le lint sur ce dépôt. Il s'exécute à chaque commit. Pour les PRs, il s'exécute sur le commit réel et sur l'arbre « après fusion ».
  • ci.yml : ce workflow ne s'exécute que sur la branche principale, une fois à chaque commit.
    1. Exécuter une commande de « pré-vérification » (vérifier les stubs, le lint, la doc, etc.) pour tous les exercices
    2. Exécuter une commande « ci » (compilation et tests) pour plusieurs versions, pour tous les exercices
  • pr.ci.yml : ce workflow ne s'exécute que sur les PRs, une fois à chaque commit.
    1. Exécuter une commande de « pré-vérification » (vérifier les stubs, le lint, la doc, etc.) pour les fichiers modifiés
    2. Exécuter une commande « ci » (compilation et tests) pour plusieurs versions, pour les exercices modifiés

Les workflows hors PR peuvent aussi être déclenchés via workflow_dispatch.

Chaque fichier indique en haut quels « scripts » doivent être disponibles. Si tu veux que ce soient des binaires, remplace scripts/xxx par bin/xxx. Certains outils exigent que les binaires se trouvent dans un dossier bin.

  • scripts/ci : un script qui doit compiler et tester tous les exercices en utilisant les solutions d'exemple face aux tests
  • scripts/ci-check : un script qui doit lancer le lint sur tous les exercices et, éventuellement, vérifier les stubs, l'intégrité de la configuration, etc.
  • scripts/pr : identique à scripts/ci, mais ne doit exécuter que les exercices déterminés à partir des chemins fournis en entrée
  • scripts/pr-check : identique à scripts/ci-check, mais ne doit s'exécuter que pour les fichiers ou exercices déterminés à partir des chemins fournis en entrée

Résolution de problèmes

Si tu rencontres le moindre problème ou si tu veux que quelqu'un relise tes workflows, n'hésite pas à mentionner l'équipe @exercism/github-actions.

Tu as modifié un fichier de premier niveau qui devrait déclencher une exécution CI sur tous les exercices

Au moment où ces lignes sont écrites, pr.ci.yml ne permet de tester que par « extension ». L'idéal serait de le mettre à jour pour qu'il se déclenche toujours lorsque certains fichiers changent (par exemple le binaire qui exécute les tests). Cependant, ces changements sont souvent peu fréquents et faits par les mainteneurs, si bien que le fait que ci.yml s'exécute sur main, toujours, pour tout, est probablement suffisamment sûr.

Tu as créé un fichier scripts/xxx sous Windows et il ne fonctionne plus sur {autre OS}

Par défaut, les fichiers créés sous Windows n'ont pas de métadonnées intégrées dans le git-index concernant leur caractère exécutable, car le modèle de permissions sous Windows est différent. Par défaut, Git utilise les métadonnées du git-index pour déterminer si un fichier doit être exécutable sur les systèmes POSIX, et rend donc le fichier scripts/xxx NON exécutable.

git update-index --chmod=+x scripts/xxx
git commit -m "Make scripts/xxx executable"