configlet sync

Sincronizzare i dati degli esercizi con il repo problem-specifications

Un esercizio di pratica su una traccia di Exercism è spesso implementato a partire da una specifica presente nel repo exercism/problem-specifications.

Exercism richiede deliberatamente che ogni esercizio abbia la propria copia di alcuni file (come .docs/instructions.md), anche quando quell'esercizio esiste già in problem-specifications. Per questo configlet ha un comando sync, che può verificare che tali esercizi di pratica su una traccia siano sincronizzati con quella fonte upstream, e può aggiornarli quando sono disponibili aggiornamenti.

Ci sono tre tipi di dati che possono essere aggiornati da problem-specifications: la documentazione, i metadati e i test. C'è anche un tipo di dati che può essere popolato dal file config.json a livello di traccia: i percorsi dei file nei file di configurazione degli esercizi.

Descriviamo la verifica e l'aggiornamento di questi tipi di dati nelle singole sezioni qui sotto, ma ecco un breve riepilogo:

• configlet sync opera solo sugli esercizi che esistono nel file config.json a livello di traccia. Perciò, se stai implementando un nuovo esercizio su una traccia e vuoi aggiungere i file iniziali con configlet sync, aggiungi prima l'esercizio al file config.json a livello di traccia. Se l'esercizio non è ancora pronto per essere mostrato agli utenti, imposta il suo valore status su wip.
• Un semplice configlet sync non apporta modifiche alla traccia e verifica ogni tipo di dati per ogni esercizio.
• Per operare su un sottoinsieme di tipi di dati, usa una combinazione delle opzioni --docs, --filepaths, --metadata e --tests.
• Per aggiornare i dati sulla traccia in modo interattivo, usa l'opzione --update.
• Per aggiornare in modo non interattivo documentazione, percorsi dei file e metadati sulla traccia, usa --update --yes.
• Per includere in modo non interattivo ogni test non visto per un dato esercizio, usa ad es. --update --tests include --exercise prime-factors.
• Per evitare di scaricare il repo problem-specifications, aggiungi --offline --prob-specs-dir /path/to/local/problem-specifications
• Nota che configlet sync cerca di mantenere l'ordine delle chiavi nei file .meta/config.json degli esercizi durante l'aggiornamento. Per scrivere questi file in forma canonica senza sincronizzare, usa il comando configlet fmt. Tuttavia, configlet sync aggiunge le chiavi obbligatorie (possibilmente vuote) (authors, files, blurb) quando mancano. Questo è meno «da sync», ma più ergonomico: quando implementi un nuovo esercizio, puoi usare sync per creare un file .meta/config.json iniziale.
• configlet sync rimuove le chiavi che non sono nella specifica. Le coppie chiave/valore personalizzate sono comunque supportate: devono essere scritte all'interno di un oggetto JSON chiamato custom.
• Il codice di uscita è 0 quando, all'uscita di configlet, tutti i dati visti sono sincronizzati, e 1 altrimenti.

Nota che nelle release di configlet 4.0.0-alpha.34 e precedenti, il comando sync operava solo sui test.

Utilizzo

Il comando sync può essere usato per verificare o aggiornare documentazione, metadati e test degli esercizi di pratica da «problem-specifications». Può anche verificare o popolare i valori files mancanti per gli esercizi di concetto e di pratica a partire dalla «config.json» della traccia.

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)

Documentazione

Un esercizio di pratica derivato dal repo problem-specifications deve avere un file .docs/instructions.md (e possibilmente anche un file .docs/introduction.md) che contiene la documentazione dell'esercizio da problem-specifications.

Per verificare, per ogni esercizio di pratica sulla traccia, se sono disponibili aggiornamenti della documentazione (uscendo con un codice di uscita diverso da zero se è disponibile almeno un aggiornamento):

configlet sync --docs

Per aggiornare la documentazione di ogni esercizio di pratica in modo interattivo, aggiungi l'opzione --update (o -u in breve):

configlet sync --docs --update

Per aggiornare la documentazione di ogni esercizio di pratica in modo non interattivo, aggiungi l'opzione --yes (o -y in breve):

configlet sync --docs --update --yes

Per operare su un singolo esercizio di pratica, usa l'opzione --exercise (o -e in breve). Ad esempio, per aggiornare in modo non interattivo la documentazione dell'esercizio prime-factors:

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

Metadati

Ogni esercizio su una traccia deve avere un file .meta/config.json. Per un esercizio di pratica derivato dal repo problem-specifications, questo file dovrebbe contenere le coppie chiave/valore blurb, source e source_url presenti nel corrispondente file metadata.toml upstream.

Per verificare, per ogni esercizio di pratica, se sono disponibili aggiornamenti dei metadati (uscendo con un codice di uscita diverso da zero se è disponibile almeno un aggiornamento):

configlet sync --metadata

Per aggiornare i metadati di ogni esercizio di pratica in modo interattivo, aggiungi l'opzione --update (o -u in breve):

configlet sync --metadata --update

Per aggiornare i metadati di ogni esercizio di pratica in modo non interattivo, aggiungi l'opzione --yes (o -y in breve):

configlet sync --metadata --update --yes

Per operare su un singolo esercizio di pratica, usa l'opzione --exercise (o -e in breve). Ad esempio, per aggiornare in modo non interattivo i metadati dell'esercizio prime-factors:

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

Test

Se una traccia implementa un esercizio per cui esistono dati di test nel repo problem-specifications, l'esercizio deve contenere un file .meta/tests.toml. Lo scopo del file tests.toml è tenere traccia di quali test sono implementati dall'esercizio. I test in questo file sono identificati dal loro UUID e ogni test ha un valore booleano che indica se è implementato da quell'esercizio.

Un file tests.toml ha questo formato:

# 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"

In questo caso, la traccia ha scelto di implementare due dei tre test disponibili. Se una traccia usa un generatore di test per generare la suite di test di un esercizio, deve usare il contenuto del file tests.toml per determinare quali test includere nella suite di test generata.

Per verificare, per ogni file tests.toml degli esercizi di pratica, se sono disponibili aggiornamenti dei test (uscendo con un codice di uscita diverso da zero se c'è almeno un caso di test che compare nei dati canonici dell'esercizio ma non nel tests.toml):

configlet sync --tests

Per aggiornare in modo interattivo il file tests.toml di ogni esercizio di pratica, aggiungi l'opzione --update:

configlet sync --tests --update

Per ogni test mancante, configlet chiede all'utente di scegliere se includerlo, escluderlo o saltarlo, e aggiorna di conseguenza il file tests.toml corrispondente. Configlet scrive il file tests.toml di un esercizio quando l'utente ha finito di fare le scelte per quell'esercizio. Questo significa che puoi terminare configlet a un prompt (ad esempio, premendo Ctrl-C nel terminale) e perdere solo le decisioni di sincronizzazione per al massimo un esercizio.

Per includere in modo non interattivo ogni caso di test non visto, usa --tests include. Ad esempio, per farlo per un esercizio chiamato prime-factors:

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

Ricorda di implementare davvero questi test sulla traccia!

Percorsi dei file

Infine, il comando sync gestisce anche la «sincronizzazione» da una fonte che non è problem-specifications: il file config.json a livello di traccia. Ogni esercizio di concetto e ogni esercizio di pratica deve avere un file .meta/config.json con un oggetto files che specifica le posizioni (relative) dei file usati dall'esercizio. Tali percorsi dei file di solito seguono uno schema semplice, quindi configlet può popolare i valori a livello di esercizio a partire dagli schemi nella chiave files del file config.json a livello di traccia.

Per verificare che ogni esercizio di concetto e ogni esercizio di pratica sulla traccia abbia una chiave files completamente popolata (o almeno una che non possa essere popolata dalla chiave files a livello di traccia):

configlet sync --filepaths

(Nota che anche configlet lint produrrà un errore quando un esercizio ha una chiave files mancante o vuota.)

Per popolare i valori vuoti o mancanti della chiave files a livello di esercizio per ogni esercizio di concetto e ogni esercizio di pratica, usando gli schemi nella chiave files a livello di traccia:

configlet sync --filepaths --update

Per farlo in modo non interattivo e per un singolo esercizio chiamato prime-factors:

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

Usare sync quando si aggiunge un nuovo esercizio a una traccia

Il comando sync è utile quando si aggiunge un nuovo esercizio a una traccia. Se stai aggiungendo un esercizio di pratica chiamato foo che esiste in problem-specifications, un possibile flusso di lavoro è:

1. Aggiungi manualmente una voce al file config.json a livello di traccia per l'esercizio foo. Questo rende l'esercizio visibile a configlet sync.
2. Esegui configlet sync --docs --filepaths --metadata -uy -e foo per creare la documentazione dell'esercizio e un file .meta/config.json iniziale con i valori files, blurb e forse source e source_url popolati.
3. Modifica il file .meta/config.json dell'esercizio come desideri. Ad esempio, aggiungiti all'array authors.
4. Esegui configlet sync --tests include -u -e foo per creare un file .meta/tests.toml con tutti i test inclusi.
5. Esamina quel file .meta/tests.toml e aggiungi include = false a ogni caso di test che l'esercizio non implementerà.
6. Implementa i test per l'esercizio in modo che corrispondano a quelli inclusi in .meta/tests.toml.
7. Aggiungi gli altri file richiesti.