configlet sync

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

Um exercício de prática de um percurso 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 certos ficheiros (como .docs/instructions.md), mesmo quando esse exercício já existe em problem-specifications. Por isso, o configlet tem um comando sync, que consegue verificar se esses exercícios de prática de um percurso estão sincronizados com essa fonte de origem, e consegue atualizá-los quando há atualizações disponíveis.

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

Descrevemos a verificação e a atualização destes tipos de dados em secções individuais abaixo, mas, em resumo:

  • O configlet sync só funciona com exercícios que existem no ficheiro config.json ao nível do percurso. Por isso, se estiveres a implementar um novo exercício num percurso e quiseres adicionar os ficheiros iniciais com o configlet sync, adiciona primeiro o exercício ao ficheiro config.json ao nível do percurso. Se o exercício ainda não estiver pronto para ser visível aos utilizadores, define o valor de status como wip.
  • Um configlet sync simples não faz alterações ao percurso, e verifica todos os tipos de dados de todos os exercícios.
  • Para trabalhar apenas com um subconjunto de tipos de dados, usa uma combinação das opções --docs, --filepaths, --metadata e --tests.
  • Para atualizar dados no percurso de forma interativa, usa a opção --update.
  • Para atualizar a documentação, os caminhos de ficheiro e os metadados no percurso de forma não interativa, usa --update --yes.
  • Para incluir de forma não interativa todos os testes ainda não vistos de um dado exercício, usa, por exemplo, --update --tests include --exercise prime-factors.
  • Para evitar descarregar o repositório problem-specifications, acrescenta --offline --prob-specs-dir /path/to/local/problem-specifications
  • Repara que o configlet sync tenta manter a ordem das chaves nos ficheiros .meta/config.json dos exercícios quando os atualiza. Para escrever estes ficheiros numa forma canónica sem sincronizar, usa o comando configlet fmt. No entanto, o configlet sync acrescenta mesmo chaves obrigatórias (possivelmente vazias) (authors, files, blurb) quando estas faltam. Isto é menos «parecido com uma sincronização», mas mais ergonómico: ao implementar um novo exercício, podes usar o sync para criar um ficheiro .meta/config.json inicial.
  • O configlet sync remove as chaves que não estão na especificação. Os pares chave/valor personalizados continuam a ser suportados: têm de ser escritos dentro de um objeto JSON chamado custom.
  • O código de saída é 0 quando todos os dados vistos estão sincronizados no momento em que o configlet termina, e 1 caso contrário.

Repara que, nas versões 4.0.0-alpha.34 e anteriores do configlet, o comando sync só funcionava com testes.

Utilização

O comando sync pode ser usado para verificar ou atualizar a documentação, os metadados e os testes dos exercícios de prática a partir do 'problem-specifications'. Também pode verificar ou preencher valores files em falta nos exercícios de conceito e de prática a partir do 'config.json' do percurso.

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)

Documentação

Um exercício de prática derivado do repositório problem-specifications tem de ter um ficheiro .docs/instructions.md (e possivelmente também um ficheiro .docs/introduction.md) com a documentação do exercício que vem do problem-specifications.

Para verificar se há atualizações de documentação disponíveis para todos os exercícios de prática do percurso (terminando com um código de saída diferente de zero se houver pelo menos uma atualização disponível):

configlet sync --docs

Para atualizar a documentação de todos os exercícios de prática de forma interativa, acrescenta a opção --update (ou -u, a forma abreviada):

configlet sync --docs --update

Para atualizar a documentação de todos os exercícios de prática de forma não interativa, acrescenta a opção --yes (ou -y, a forma abreviada):

configlet sync --docs --update --yes

Para trabalhar com um único exercício de prática, usa a opção --exercise (ou -e, a forma abreviada). Por exemplo, para atualizar a documentação do exercício prime-factors de forma não interativa:

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

Metadados

Cada exercício de um percurso tem de ter um ficheiro .meta/config.json. No caso de um exercício de prática derivado do repositório problem-specifications, este ficheiro deve conter os pares chave/valor blurb, source e source_url que existem no ficheiro metadata.toml correspondente da fonte de origem.

Para verificar se há atualizações de metadados disponíveis para todos os exercícios de prática (terminando com um código de saída diferente de zero se houver pelo menos uma atualização disponível):

configlet sync --metadata

Para atualizar os metadados de todos os exercícios de prática de forma interativa, acrescenta a opção --update (ou -u, a forma abreviada):

configlet sync --metadata --update

Para atualizar os metadados de todos os exercícios de prática de forma não interativa, acrescenta a opção --yes (ou -y, a forma abreviada):

configlet sync --metadata --update --yes

Para trabalhar com um único exercício de prática, usa a opção --exercise (ou -e, a forma abreviada). Por exemplo, para atualizar os metadados do exercício prime-factors de forma não interativa:

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

Testes

Se um percurso implementa um exercício para o qual existem dados de teste no repositório problem-specifications, o exercício tem de conter um ficheiro .meta/tests.toml. O objetivo do ficheiro tests.toml é registar que testes são implementados pelo exercício. Os testes neste ficheiro são identificados pelo seu UUID e cada teste tem um valor Boolean que indica se é implementado por esse exercício.

Um ficheiro tests.toml tem este 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"

Neste caso, o percurso decidiu implementar dois dos três testes disponíveis. Se um percurso usar um gerador de testes para gerar o conjunto de testes de um exercício, tem de usar o conteúdo do ficheiro tests.toml para determinar que testes incluir no conjunto de testes gerado.

Para verificar se há atualizações de testes disponíveis em todos os ficheiros tests.toml dos exercícios de prática (terminando com um código de saída diferente de zero se houver pelo menos um caso de teste que aparece nos dados canónicos do exercício, mas não no tests.toml):

configlet sync --tests

Para atualizar o ficheiro tests.toml de todos os exercícios de prática de forma interativa, acrescenta a opção --update:

configlet sync --tests --update

Para cada teste em falta, isto pede ao utilizador que escolha se o deve incluir, excluir ou ignorar, e atualiza o ficheiro tests.toml correspondente em conformidade. O configlet escreve o ficheiro tests.toml de um exercício quando o utilizador termina de fazer as escolhas para esse exercício. Isto significa que podes terminar o configlet num pedido de confirmação (por exemplo, premindo Ctrl-C no terminal) e perder apenas as decisões de sincronização de, no máximo, um exercício.

Para incluir de forma não interativa todos os casos de teste ainda não vistos, usa --tests include. Por exemplo, para o fazer num exercício chamado prime-factors:

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

Não te esqueças de implementar mesmo estes testes no percurso!

Caminhos de ficheiro

Por fim, o comando sync também trata da «sincronização» a partir de uma fonte que não é o problem-specifications: o ficheiro config.json ao nível do percurso. Cada exercício de conceito e cada exercício de prática tem de ter um ficheiro .meta/config.json com um objeto files que especifica as localizações (relativas) dos ficheiros que o exercício usa. Estes caminhos de ficheiro seguem normalmente um padrão simples, pelo que o configlet consegue preencher os valores ao nível do exercício a partir dos padrões na chave files do ficheiro config.json ao nível do percurso.

Para verificar que todos os exercícios de conceito e de prática do percurso têm uma chave files totalmente preenchida (ou pelo menos uma que não pode ser preenchida a partir da chave files ao nível do percurso):

configlet sync --filepaths

(Repara que o configlet lint também dá um erro quando um exercício tem uma chave files em falta ou vazia.)

Para preencher os valores vazios ou em falta da chave files ao nível do exercício em todos os exercícios de conceito e de prática, a partir dos padrões da chave files ao nível do percurso:

configlet sync --filepaths --update

Para o fazer de forma não interativa e para um único exercício chamado prime-factors:

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

Como usar o sync quando adicionas um novo exercício a um percurso

O comando sync é útil quando adicionas um novo exercício a um percurso. Se estiveres a adicionar um exercício de prática chamado foo que existe no problem-specifications, um fluxo de trabalho possível é:

  1. Adiciona manualmente uma entrada no ficheiro config.json ao nível do percurso para o exercício foo. Isto torna o exercício visível para o configlet sync.
  2. Executa configlet sync --docs --filepaths --metadata -uy -e foo para criar a documentação do exercício e um ficheiro .meta/config.json inicial com os valores files, blurb e, possivelmente, source e source_url preenchidos.
  3. Edita o ficheiro .meta/config.json do exercício como quiseres. Por exemplo, adiciona-te ao array authors.
  4. Executa configlet sync --tests include -u -e foo para criar um ficheiro .meta/tests.toml com todos os testes incluídos.
  5. Vê esse ficheiro .meta/tests.toml e acrescenta include = false a qualquer caso de teste que o exercício não vai implementar.
  6. Implementa os testes do exercício de modo a corresponderem aos incluídos no .meta/tests.toml.
  7. Acrescenta os outros ficheiros necessários.