configlet sync

Synchronise les données d'exercice avec le dépôt problem-specifications

Un exercice d'entraînement sur un parcours Exercism 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 synchronisés avec cette source en 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. Il existe aussi un type de données qui peut être renseigné à partir du fichier config.json au niveau du parcours : les chemins de fichiers dans les fichiers de configuration d'exercice.

On décrit la vérification et la mise à jour de ces types de données dans des sections distinctes ci-dessous, mais pour résumer :

  • configlet sync n'agit que sur les exercices qui existent dans le fichier config.json au niveau du parcours. Par conséquent, si tu implémentes un nouvel exercice sur un parcours et que tu veux ajouter les fichiers initiaux avec configlet sync, ajoute d'abord l'exercice au fichier config.json au niveau du parcours. Si l'exercice n'est pas encore prêt à être visible par les utilisateurs, mets sa valeur status à wip.
  • Un simple configlet sync n'apporte aucune modification au parcours et vérifie chaque type de données pour chaque exercice.
  • Pour n'agir que sur un sous-ensemble de types de données, combine les options --docs, --filepaths, --metadata et --tests.
  • Pour mettre à jour les données du parcours de façon interactive, utilise l'option --update.
  • Pour mettre à jour la documentation, les chemins de fichiers et les métadonnées du parcours sans interaction, utilise --update --yes.
  • Pour inclure sans interaction tous les tests non encore vus d'un exercice donné, utilise par exemple --update --tests include --exercise prime-factors.
  • Pour éviter de télécharger le dépôt problem-specifications, ajoute --offline --prob-specs-dir /path/to/local/problem-specifications
  • À noter que configlet sync s'efforce de conserver l'ordre des clés dans les fichiers .meta/config.json des exercices lors de la mise à jour. Pour écrire ces fichiers sous une forme canonique sans synchroniser, utilise la commande configlet fmt. Cependant, configlet sync ajoute bien les clés obligatoires (éventuellement vides) authors, files et blurb lorsqu'elles sont absentes. C'est moins « dans l'esprit de la synchronisation », mais plus pratique : quand tu implémentes un nouvel exercice, tu peux utiliser sync pour créer un fichier .meta/config.json de départ.
  • configlet sync supprime les clés qui ne figurent pas dans la spécification. Les paires clé/valeur personnalisées restent prises en charge : elles doivent être écrites dans un objet JSON nommé custom.
  • Le code de sortie vaut 0 lorsque toutes les données vues sont synchronisées au moment où configlet se termine, et 1 sinon.

À noter que dans les versions 4.0.0-alpha.34 et antérieures de configlet, la commande sync n'agissait que sur les tests.

Utilisation

La commande sync permet de vérifier ou de mettre à jour la documentation, les métadonnées et les tests des exercices d'entraînement à partir de 'problem-specifications'. Elle peut aussi vérifier ou renseigner les valeurs files manquantes des exercices d'apprentissage/d'entraînement à partir du 'config.json' du parcours.

configlet [global-options] sync [command-options]

Global options:
  -h, --help                   Show this help message and exit
      --version                Show this tool's version information and exit
  -t, --track-dir <dir>        Specify a track directory to use instead of the current directory
  -v, --verbosity <verbosity>  The verbosity of output. Allowed values: q[uiet], n[ormal], d[etailed]

Options for sync:
  -e, --exercise <slug>        Only operate on this exercise
  -p, --prob-specs-dir <dir>   Use this 'problem-specifications' directory, rather than cloning temporarily
  -o, --offline                Do not check that the directory specified by --prob-specs-dir is up to date
  -u, --update                 Prompt to update the seen data that are unsynced
  -y, --yes                    Auto-confirm prompts from --update for updating docs, filepaths, and metadata
      --docs                   Sync Practice Exercise '.docs/introduction.md' and '.docs/instructions.md' files
      --filepaths              Populate empty 'files' values in Concept/Practice exercise '.meta/config.json' files
      --metadata               Sync Practice Exercise '.meta/config.json' metadata values
      --tests [mode]           Sync Practice Exercise '.meta/tests.toml' files.
                               The mode value specifies how missing tests are handled when using --update.
                               Allowed values: c[hoose], i[nclude], e[xclude] (default: choose)

Documentation

Un exercice d'entraînement dérivé du dépôt problem-specifications doit avoir un fichier .docs/instructions.md (et éventuellement aussi un fichier .docs/introduction.md) contenant la documentation de l'exercice issue de problem-specifications.

Pour vérifier si des mises à jour de documentation sont disponibles pour chaque exercice d'entraînement du parcours (en sortant avec un code de sortie non nul si au moins une mise à jour est disponible) :

configlet sync --docs

Pour mettre à jour la documentation de chaque exercice d'entraînement de façon interactive, ajoute l'option --update (ou -u en abrégé) :

configlet sync --docs --update

Pour mettre à jour la documentation de chaque exercice d'entraînement sans interaction, ajoute l'option --yes (ou -y en abrégé) :

configlet sync --docs --update --yes

Pour n'agir que sur un seul exercice d'entraînement, utilise l'option --exercise (ou -e en abrégé). Par exemple, pour mettre à jour la documentation de l'exercice prime-factors sans interaction :

configlet sync --docs -uy -e prime-factors

Métadonnées

Chaque exercice d'un parcours doit avoir un fichier .meta/config.json. Pour un exercice d'entraînement dérivé du dépôt problem-specifications, ce fichier doit contenir les paires clé/valeur blurb, source et source_url présentes dans le fichier metadata.toml correspondant en amont.

Pour vérifier si des mises à jour de métadonnées sont disponibles pour chaque exercice d'entraînement (en sortant avec un code de sortie non nul si au moins une mise à jour est disponible) :

configlet sync --metadata

Pour mettre à jour les métadonnées de chaque exercice d'entraînement de façon interactive, ajoute l'option --update (ou -u en abrégé) :

configlet sync --metadata --update

Pour mettre à jour les métadonnées de chaque exercice d'entraînement sans interaction, ajoute l'option --yes (ou -y en abrégé) :

configlet sync --metadata --update --yes

Pour n'agir que sur un seul exercice d'entraînement, utilise l'option --exercise (ou -e en abrégé). Par exemple, pour mettre à jour les métadonnées de l'exercice prime-factors sans interaction :

configlet sync --metadata -uy -e prime-factors

Tests

Si un parcours implémente un exercice pour lequel des données de test existent dans le dépôt problem-specifications, l'exercice doit contenir un fichier .meta/tests.toml. Le but du fichier tests.toml est de garder la trace des tests qui sont implémentés par l'exercice. 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.

Un fichier tests.toml a ce format :

# This is an auto-generated file.
#
# Regenerating this file via `configlet sync` will:
# - Recreate every `description` key/value pair
# - Recreate every `reimplements` key/value pair, where they exist in problem-specifications
# - Remove any `include = true` key/value pair (an omitted `include` key implies inclusion)
# - Preserve any other key/value pair
#
# As user-added comments (using the # character) will be removed when this file
# is regenerated, comments can be added via a `comment` key.
[1e22cceb-c5e4-4562-9afe-aef07ad1eaf4]
description = "basic"
[79ae3889-a5c0-4b01-baf0-232d31180c08]
description = "lowercase words"
[ec7000a7-3931-4a17-890e-33ca2073a548]
description = "invalid input"
include = false
comment = "excluded because we don't want to add error handling to the exercise"

Dans ce cas, le parcours a choisi d'implémenter deux des trois tests disponibles. Si un parcours utilise un générateur de tests pour générer la suite de tests d'un exercice, il doit utiliser le contenu du fichier tests.toml pour déterminer quels tests inclure dans la suite de tests générée.

Pour vérifier si des mises à jour de tests sont disponibles pour chaque fichier tests.toml d'exercice d'entraînement (en sortant avec un code de sortie non nul s'il existe au moins un cas de test qui apparaît dans les données canoniques de l'exercice, mais pas dans le tests.toml) :

configlet sync --tests

Pour mettre à jour le fichier tests.toml de chaque exercice d'entraînement de façon interactive, ajoute l'option --update :

configlet sync --tests --update

Pour chaque test manquant, cela demande à l'utilisateur de choisir de l'inclure, de l'exclure ou de le passer, puis met à jour le fichier tests.toml correspondant en conséquence. Configlet écrit le fichier tests.toml d'un exercice lorsque l'utilisateur a terminé de faire ses choix pour cet exercice. Cela signifie que tu peux interrompre configlet au niveau d'une invite (par exemple en appuyant sur Ctrl-C dans le terminal) et ne perdre les décisions de synchronisation que pour un seul exercice au maximum.

Pour inclure sans interaction tous les cas de test non encore vus, utilise --tests include. Par exemple, pour le faire pour un exercice nommé prime-factors :

configlet sync --tests include -u -e prime-factors

N'oublie pas d'implémenter réellement ces tests sur le parcours !

Chemins de fichiers

Enfin, la commande sync gère aussi la « synchronisation » depuis une source qui n'est pas problem-specifications : le fichier config.json au niveau du parcours. Chaque exercice d'apprentissage et chaque exercice d'entraînement doit avoir un fichier .meta/config.json avec un objet files qui précise les emplacements (relatifs) des fichiers que l'exercice utilise. Ces chemins de fichiers suivent généralement un schéma simple, et configlet peut donc renseigner les valeurs au niveau de l'exercice à partir des motifs de la clé files du fichier config.json au niveau du parcours.

Pour vérifier que chaque exercice d'apprentissage et chaque exercice d'entraînement du parcours a une clé files entièrement renseignée (ou du moins une clé qui ne peut pas être renseignée à partir de la clé files au niveau du parcours) :

configlet sync --filepaths

(À noter que configlet lint produit aussi une erreur quand un exercice a une clé files manquante ou vide.)

Pour renseigner les valeurs vides ou manquantes de la clé files au niveau de l'exercice pour chaque exercice d'apprentissage et chaque exercice d'entraînement, à partir des motifs de la clé files au niveau du parcours :

configlet sync --filepaths --update

Pour le faire sans interaction et pour un seul exercice nommé prime-factors :

configlet sync --filepaths -uy -e prime-factors

Utilise sync quand tu ajoutes un nouvel exercice à un parcours

La commande sync est utile quand tu ajoutes un nouvel exercice à un parcours. Si tu ajoutes un exercice d'entraînement nommé foo qui existe dans problem-specifications, un workflow possible est le suivant :

  1. Ajoute manuellement une entrée pour l'exercice foo dans le fichier config.json au niveau du parcours. Cela rend l'exercice visible pour configlet sync.
  2. Lance configlet sync --docs --filepaths --metadata -uy -e foo pour créer la documentation de l'exercice, ainsi qu'un fichier .meta/config.json de départ avec des valeurs files et blurb renseignées, et peut-être source et source_url.
  3. Modifie le fichier .meta/config.json de l'exercice comme tu le souhaites. Par exemple, ajoute-toi au tableau authors.
  4. Lance configlet sync --tests include -u -e foo pour créer un fichier .meta/tests.toml avec tous les tests inclus.
  5. Ouvre ce fichier .meta/tests.toml et ajoute include = false à tout cas de test que l'exercice n'implémentera pas.
  6. Implémente les tests de l'exercice pour qu'ils correspondent à ceux inclus dans .meta/tests.toml.
  7. Ajoute les autres fichiers obligatoires.