configlet est un outil qui aide les mainteneurs de parcours à assurer la maintenance de leur parcours.
Linting
La fonction principale de configlet est de faire du linting : vérifier que les fichiers (de configuration) d'un parcours sont correctement structurés, tant sur le plan syntaxique que sémantique. Un parcours mal configuré risque de ne pas se synchroniser correctement, de sembler erroné sur le site ou d'offrir une expérience utilisateur médiocre ; les garde-fous de configlet jouent donc un rôle important pour préserver l'intégrité d'Exercism. La liste complète des règles vérifiées par le linter est disponible ici.
Génère des documents
La fonction secondaire de configlet est de générer des documents. Configlet peut générer deux types de documents :
- Le fichier
introduction.md d'un exercice d'apprentissage.
- Le fichier
instructions.md d'un exercice d'entraînement.
Pour savoir comment ces documents sont générés, consulte cette page.
Synchronise les données d'exercices avec le dépôt problem-specifications
La fonction tertiaire de configlet est de fournir diverses données pour les exercices d'entraînement.
Sur un parcours Exercism, un exercice d'entraînement est souvent implémenté à partir d'une spécification du dépôt exercism/problem-specifications.
Exercism exige délibérément que chaque exercice ait sa propre copie de certains fichiers (comme .docs/instructions.md), même lorsque cet exercice existe dans problem-specifications. C'est pourquoi configlet dispose d'une commande sync, qui peut vérifier que ces exercices d'entraînement d'un parcours sont bien synchronisés avec cette source amont, et les mettre à jour lorsque des mises à jour sont disponibles.
Trois types de données peuvent être mis à jour depuis problem-specifications : la documentation, les métadonnées et les tests. Un autre type de données peut être renseigné à partir du fichier config.json du parcours : les chemins de fichiers dans les fichiers de configuration des exercices.
À noter que dans les versions 4.0.0-alpha.34 et antérieures de configlet, la commande sync n'agissait que sur les tests.
Pour savoir quels tests sont implémentés pour un exercice d'entraînement donné, l'exercice doit contenir un fichier .meta/tests.toml. Les tests de ce fichier sont identifiés par leur UUID et chaque test possède une valeur booléenne qui indique s'il est implémenté par cet exercice.
Tu trouveras les détails sur la façon de synchroniser les différentes parties d'un exercice ici.
Crée des fichiers
Configlet permet de créer rapidement la structure des fichiers d'une nouvelle approche, d'un nouvel article ou d'un nouvel exercice.
Pour en savoir plus sur la création de ces fichiers, consulte cette page.
Génère des UUID
Les exercices, les parcours et les concepts sont identifiés par un UUID.
Pour savoir comment générer des UUID, consulte cette page.
Configlet dispose d'une commande fmt qui aide à formater de manière cohérente les fichiers JSON du dépôt du parcours. La commande fmt formate les fichiers suivants :
config.jsonexercises/{concept,practice}/*/.approaches/config.jsonexercises/{concept,practice}/*/.articles/config.jsonexercises/{concept,practice}/*/.meta/config.json
Pour en savoir plus sur la commande fmt, consulte cette page.
Installation
configlet est distribué sous forme de binaire autonome. Chaque parcours doit avoir un script bin/fetch-configlet, et peut aussi avoir un script bin/fetch-configlet.ps1. Le premier est un script bash, et le second un script PowerShell.
Exécuter l'un de ces scripts télécharge la dernière version de configlet dans le répertoire bin. Tu peux ensuite utiliser configlet en lançant bin/configlet ou bin/configlet.exe respectivement.
CI
Tous les parcours devraient intégrer la fonctionnalité de linting de configlet dans leur configuration d'intégration continue (CI). Le plus simple est d'utiliser l'action GitHub configlet CI.
