Configlet

configlet è uno strumento che aiuta i manutentori di una traccia nella manutenzione della loro traccia.

Linting

La funzione principale di configlet è fare linting: verificare che i file (di configurazione) di una traccia siano strutturati correttamente, sia sintatticamente che semanticamente. Le tracce configurate male potrebbero non sincronizzarsi correttamente, apparire sbagliate sul sito o offrire un'esperienza utente non ottimale: per questo i controlli di configlet svolgono un ruolo importante nel preservare l'integrità di Exercism. L'elenco completo delle regole controllate dal linter è disponibile qui.

Generare documenti

La funzione secondaria di configlet è generare documenti. I tipi di documenti che configlet può generare sono due:

1. Il file introduction.md di un esercizio concettuale.
2. Il file instructions.md di un esercizio pratico.

Come vengono generati questi documenti è descritto qui.

Sincronizzare i dati degli esercizi con il repository problem-specifications

La funzione terziaria di configlet è fornire vari dati per gli esercizi pratici.

Spesso un esercizio pratico di una traccia Exercism viene realizzato a partire da una specifica presente nel repository exercism/problem-specifications.

Exercism richiede di proposito 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 pratici di una traccia siano sincronizzati con quella fonte a monte e può aggiornarli quando sono disponibili nuovi aggiornamenti.

Ci sono tre tipi di dati che possono essere aggiornati da problem-specifications: documentazione, metadati e 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.

Tieni presente che nelle release di configlet 4.0.0-alpha.34 e precedenti, il comando sync agiva solo sui test.

Per tenere traccia di quali test sono implementati per un determinato esercizio pratico, l'esercizio deve contenere un file .meta/tests.toml. I test in questo file sono identificati dal loro UUID e ogni test ha un valore booleano che indica se è implementato da quell'esercizio.

I dettagli su come sincronizzare le diverse parti di un esercizio sono qui.

Creare file

Configlet può essere usato per creare rapidamente lo scheletro dei file per un nuovo approccio, un nuovo articolo o un nuovo esercizio.

Per saperne di più su come creare questi file, vai qui.

Generare UUID

Esercizi, tracce e concetti sono identificati da un UUID.

Come generare gli UUID è descritto qui.

Formattazione

Configlet ha un comando fmt che aiuta a formattare in modo coerente i file JSON nel repository della traccia. Il comando fmt formatta i seguenti file:

• config.json
• exercises/{concept,practice}/*/.approaches/config.json
• exercises/{concept,practice}/*/.articles/config.json
• exercises/{concept,practice}/*/.meta/config.json

Per saperne di più sul comando di formattazione, vai qui.

Installazione

configlet viene distribuito come binario autonomo. Ogni traccia dovrebbe avere uno script bin/fetch-configlet e potrebbe avere anche uno script bin/fetch-configlet.ps1. Il primo è uno script bash, il secondo è uno script PowerShell.

Eseguire uno di questi script scarica la versione più recente di configlet nella cartella bin. Poi puoi usare configlet eseguendo rispettivamente bin/configlet o bin/configlet.exe.

CI

Tutte le tracce dovrebbero integrare la funzionalità di lint di configlet nella loro configurazione CI. Il modo più semplice è usare la GitHub action configlet CI.