Ajoute un exercice d'entraînement

Ce document explique comment ajouter un nouvel exercice d'entraînement.

Sélectionne un exercice

Le plus simple pour vérifier quels exercices d'entraînement n'ont pas encore été implémentés est d'aller sur la page de build du parcours (par exemple https://exercism.org/tracks/csharp/build) et de consulter la section « Exercices d'entraînement ».

Caution

Les données de la page de build sont mises à jour une fois par jour.

Génère la structure de l'exercice

Tu peux rapidement générer la structure d'un nouvel exercice d'entraînement en lançant le script bin/add-practice-exercise (source) depuis la racine du parcours :

bin/add-practice-exercise <exercise-slug>

Tu peux aussi préciser, si tu le souhaites, la difficulté de l'exercice (avec -d) et/ou le nom d'utilisateur GitHub de l'auteur (avec -a) :

bin/add-practice-exercise -d 3 -a foobar <exercise-slug>
Note

Si tu travailles sur un dépôt de parcours qui ne contient pas ce fichier, n'hésite pas à le copier dans ton dépôt à l'aide du lien source ci-dessus.

Implémente l'exercice

Une fois les fichiers générés, tu devras :

  • ajouter des tests au fichier de tests
  • ajouter une implémentation d'exemple
  • définir le contenu du fichier stub
  • dans le fichier .meta/config.json de l'exercice :
    • ajouter le nom d'utilisateur GitHub des auteurs de l'exercice à la clé authors
  • dans le fichier config.json du parcours :
    • vérifier ou mettre à jour la difficulté de l'exercice
    • ajouter des concepts à la clé practices (nécessaire uniquement lorsque le parcours a des exercices d'apprentissage)
    • ajouter des concepts à la clé prerequisites (nécessaire uniquement lorsque le parcours a des exercices d'apprentissage)

Ajoute des tests

Ajouter des tests est un élément essentiel de l'ajout d'un exercice. Pour un exercice d'entraînement, tu as globalement deux options :

  1. Implémenter les tests à partir de zéro, en utilisant les cas de test du fichier canonical-data.json de l'exercice, que l'on trouve dans le dépôt problem-specifications.
  2. Reprendre les tests d'une implémentation d'un autre parcours (astuce : va sur https://exercism.org/exercises/<slug> pour voir quels parcours ont implémenté un exercice donné).

La deuxième option peut être particulièrement séduisante, car elle donne des résultats rapidement. Garde toutefois à l'esprit que tu devras adapter l'implémentation pour qu'elle colle au mieux à ton parcours. Par exemple, certains parcours n'utilisent pas de classes et ne travaillent qu'avec des fonctions. Si ton parcours travaille habituellement avec des objets, adapte plutôt l'implémentation à ce qui lui convient le mieux.

Note

Certains parcours utilisent un générateur de tests pour (re)générer automatiquement le(s) fichier(s) de test d'un exercice. Consulte la documentation du parcours pour savoir s'il existe un générateur de tests et, le cas échéant, comment l'utiliser.

Ajoute une implémentation d'exemple

Pour garantir qu'il est possible d'écrire du code qui réussit les tests, il faut ajouter une implémentation d'exemple.

Note

Le code n'a pas besoin d'être idiomatique, il doit seulement réussir les tests.

Tu peux vérifier que l'implémentation d'exemple réussit tous les tests en lançant le script bin/verify-exercises (source) depuis la racine du parcours :

bin/verify-exercises <exercise-slug>

Utilise la sortie pour vérifier que l'implémentation d'exemple réussit tous les tests.

Note

Si tu travailles sur un dépôt de parcours qui ne contient pas ce fichier, n'hésite pas à le copier dans ton dépôt à l'aide du lien source ci-dessus.

Advanced

Sous le capot, le script bin/verify-exercises fait plusieurs choses :

  • copier l'exercice dans un répertoire temporaire
  • remplacer le(s) fichier(s) stub par le(s) fichier(s) d'implémentation d'exemple
  • si le fichier de test contient des tests ignorés, ils seront réactivés
  • lancer les tests

Ajoute le(s) fichier(s) stub

Le(s) fichier(s) stub d'implémentation fournissent un point de départ aux apprenants.

On recommande que les fichiers stub contiennent le minimum de code nécessaire pour que :

  • l'apprenant puisse commencer immédiatement à implémenter la logique qui réussit les tests
  • l'apprenant ne soit pas confronté à des erreurs de syntaxe « bizarres »

En pratique, cela signifie définir les fonctions/méthodes testées par la suite de tests. Les parcours sont libres quant à la façon d'organiser ce code, tant qu'ils s'assurent que le code stub échoue initialement à tous les tests.

Exemples

Python :

def two_fer(name):
    pass

Kotlin :

fun twofer(name: String): String {
    TODO("Implement the function to complete the task")
}

Passe l'exercice au linter

La dernière étape consiste à exécuter le linter pour vérifier que les fichiers (de configuration) du parcours sont correctement structurés, sur le plan syntaxique comme sémantique.

Tout d'abord, assure-toi d'avoir la dernière version de configlet en lançant :

bin/fetch-configlet

Ensuite, exécute le linter en lançant :

bin/configlet lint

Utilise la sortie pour vérifier que tout va bien.

Soumets une pull request

Une fois que tout va bien, tu peux soumettre une pull request au dépôt du parcours.

Avant de soumettre, lis le guide des pull requests pour les contributeurs et le guide des pull requests.

Assure-toi que la description de la PR mentionne l'exercice ajouté.