Configlet

O configlet é uma ferramenta que ajuda os responsáveis de um track na manutenção do seu track.

Linting

A principal função do configlet é fazer linting: verificar se os ficheiros (de configuração) de um track estão devidamente estruturados, tanto a nível sintático como semântico. Um track mal configurado pode não sincronizar corretamente, pode aparecer errado no site ou pode proporcionar uma experiência de utilizador pouco satisfatória. Por isso, as verificações do configlet desempenham um papel importante na manutenção da integridade do Exercism. A lista completa das regras verificadas pelo linter está disponível aqui.

Gerar documentos

A função secundária do configlet é gerar documentos. O configlet pode gerar dois tipos de documentos:

1. O ficheiro introduction.md de um exercício de conceito.
2. O ficheiro instructions.md de um exercício de prática.

A forma como estes documentos são gerados está descrita aqui.

Sincronizar os dados dos exercícios com o repositório problem-specifications

A terceira função do configlet é fornecer vários dados para os exercícios de prática.

Um exercício de prática num track do Exercism é muitas vezes implementado a partir de uma especificação no repositório exercism/problem-specifications.

O Exercism exige deliberadamente que cada exercício tenha a sua própria cópia de determinados ficheiros (como .docs/instructions.md), mesmo quando esse exercício existe no problem-specifications. Por isso, o configlet tem um comando sync, que pode verificar se esses exercícios de prática de um track estão sincronizados com essa fonte a montante e pode atualizá-los quando existem atualizações disponíveis.

Há três tipos de dados que podem ser atualizados a partir do problem-specifications: documentação, metadados e testes. Há também um tipo de dados que pode ser preenchido a partir do ficheiro config.json de nível de track: os caminhos dos ficheiros nos ficheiros de configuração dos exercícios.

Tem em atenção que, nas versões 4.0.0-alpha.34 e anteriores do configlet, o comando sync atuava apenas sobre os testes.

Para acompanhar quais testes estão implementados num determinado exercício de prática, o exercício tem de conter um ficheiro .meta/tests.toml. Os testes neste ficheiro são identificados pelo seu UUID e cada teste tem um valor Boolean que indica se está implementado por esse exercício.

Encontras os detalhes sobre como sincronizar as diferentes partes de um exercício aqui.

Criar ficheiros

O configlet pode ser usado para criar rapidamente o esqueleto de ficheiros para uma nova abordagem, artigo ou exercício.

Podes saber mais sobre como criar estes ficheiros aqui.

Gerar UUIDs

Os exercícios, os tracks e os conceitos são identificados por um UUID.

Podes saber como gerar UUIDs aqui.

Formatação

O configlet tem um comando fmt que ajuda a manter uma formatação consistente dos ficheiros JSON no repositório do track. O comando fmt formata os seguintes ficheiros:

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

Podes saber mais sobre o comando de formatação aqui.

Instalação

O configlet é distribuído como um binário autónomo. Cada track deve ter um script bin/fetch-configlet e pode também ter um script bin/fetch-configlet.ps1. O primeiro é um script bash e o segundo é um script PowerShell.

Executar um destes scripts transfere a versão mais recente do configlet para o diretório bin. Depois, podes usar o configlet executando bin/configlet ou bin/configlet.exe, respetivamente.

CI

Todos os tracks devem integrar a funcionalidade lint do configlet na sua configuração de CI. A forma mais fácil de o fazer é usar a GitHub Action configlet CI.