configlet sync

Sincronizando os dados de exercícios com o repositório problem-specifications

Um Exercício de Prática em uma trilha do Exercism costuma ser implementado a partir de uma especificação no repositório exercism/problem-specifications.

O Exercism exige de propósito que cada exercício tenha sua própria cópia de certos arquivos (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 em uma trilha estão sincronizados com essa fonte upstream e consegue atualizá-los quando há atualizações disponíveis.

Existem 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 dado que pode ser preenchido a partir do arquivo config.json da trilha: os caminhos de arquivo nos arquivos de configuração dos exercícios.

Descrevemos a verificação e a atualização desses tipos de dados em seções individuais abaixo, mas, como resumo rápido:

• O configlet sync só opera sobre exercícios que existem no arquivo config.json da trilha. Portanto, se você está implementando um novo exercício em uma trilha e quer adicionar os arquivos iniciais com o configlet sync, adicione o exercício ao arquivo config.json da trilha primeiro. Se o exercício ainda não está pronto para aparecer para os usuários, defina o valor de status dele como wip.
• Um configlet sync simples não faz nenhuma alteração na trilha e verifica todos os tipos de dados de todos os exercícios.
• Para operar sobre um subconjunto de tipos de dados, use alguma combinação das opções --docs, --filepaths, --metadata e --tests.
• Para atualizar dados na trilha de forma interativa, use a opção --update.
• Para atualizar documentação, caminhos de arquivo e metadados na trilha de forma não interativa, use --update --yes.
• Para incluir de forma não interativa todos os testes ainda não vistos de um determinado exercício, use, por exemplo, --update --tests include --exercise prime-factors.
• Para pular o download do repositório problem-specifications, adicione --offline --prob-specs-dir /path/to/local/problem-specifications
• Observe que o configlet sync tenta manter a ordem das chaves nos arquivos .meta/config.json dos exercícios ao atualizar. Para gravar esses arquivos em uma forma canônica sem sincronizar, use o comando configlet fmt. No entanto, o configlet sync de fato adiciona chaves obrigatórias (possivelmente vazias) (authors, files, blurb) quando elas estão ausentes. Isso é menos "parecido com uma sincronização", mas mais ergonômico: ao implementar um novo exercício, você pode usar o sync para criar um arquivo .meta/config.json inicial.
• O configlet sync remove chaves que não estão na especificação. Pares chave/valor personalizados ainda são suportados: eles precisam 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 encerra, e 1 caso contrário.

Observe que nas versões 4.0.0-alpha.34 e anteriores do configlet, o comando sync operava apenas sobre testes.

Uso

O comando sync pode ser usado para verificar ou atualizar documentação, metadados e testes de Exercícios de Prática do 'problem-specifications'. Ele também pode verificar ou preencher valores files ausentes de Exercícios de Conceito/Prática a partir do 'config.json' da trilha.

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 precisa ter um arquivo .docs/instructions.md (e possivelmente também um arquivo .docs/introduction.md) contendo a documentação do exercício vinda do problem-specifications.

Para verificar se há atualizações de documentação disponíveis para todos os Exercícios de Prática da trilha (encerrando 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, adicione a opção --update (ou -u, na forma abreviada):

configlet sync --docs --update

Para atualizar a documentação de todos os Exercícios de Prática de forma não interativa, adicione a opção --yes (ou -y, na forma abreviada):

configlet sync --docs --update --yes

Para operar sobre um único Exercício de Prática, use a opção --exercise (ou -e, na 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

Todo exercício de uma trilha precisa ter um arquivo .meta/config.json. Para um Exercício de Prática derivado do repositório problem-specifications, esse arquivo deve conter os pares chave/valor blurb, source e source_url que existem no arquivo metadata.toml upstream correspondente.

Para verificar se há atualizações de metadados disponíveis para todos os Exercícios de Prática (encerrando 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, adicione a opção --update (ou -u, na forma abreviada):

configlet sync --metadata --update

Para atualizar os metadados de todos os Exercícios de Prática de forma não interativa, adicione a opção --yes (ou -y, na forma abreviada):

configlet sync --metadata --update --yes

Para operar sobre um único Exercício de Prática, use a opção --exercise (ou -e, na 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 uma trilha implementa um exercício para o qual existem dados de teste no repositório problem-specifications, o exercício precisa conter um arquivo .meta/tests.toml. O objetivo do arquivo tests.toml é manter o controle de quais testes o exercício implementa. Os testes nesse arquivo são identificados pelo UUID e cada teste tem um valor booleano que indica se ele é implementado por aquele exercício.

Um arquivo 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"

Nesse caso, a trilha escolheu implementar dois dos três testes disponíveis. Se uma trilha usa um gerador de testes para gerar a suíte de testes de um exercício, ele precisa usar o conteúdo do arquivo tests.toml para determinar quais testes incluir na suíte de testes gerada.

Para verificar se há atualizações de testes disponíveis em cada arquivo tests.toml de Exercício de Prática (encerrando 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 arquivo tests.toml de todos os Exercícios de Prática de forma interativa, adicione a opção --update:

configlet sync --tests --update

Para cada teste ausente, isso pede que o usuário escolha entre incluir, excluir ou pular o teste, e atualiza o arquivo tests.toml correspondente de acordo. O configlet grava o arquivo tests.toml de um exercício quando o usuário termina de fazer as escolhas para aquele exercício. Isso significa que você pode encerrar o configlet em um prompt (por exemplo, pressionando Ctrl-C no terminal) e perder 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, use --tests include. Por exemplo, para fazer isso com um exercício chamado prime-factors:

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

Lembre-se de realmente implementar esses testes na trilha!

Caminhos de arquivo

Por fim, o comando sync também lida com a "sincronização" a partir de uma fonte que não é o problem-specifications: o arquivo config.json da trilha. Todo Exercício de Conceito e todo Exercício de Prática precisa ter um arquivo .meta/config.json com um objeto files que especifica as localizações (relativas) dos arquivos que o exercício usa. Esses caminhos de arquivo geralmente seguem um padrão simples, então o configlet consegue preencher os valores no nível do exercício a partir de padrões na chave files do arquivo config.json da trilha.

Para verificar se todo Exercício de Conceito e todo Exercício de Prática da trilha tem uma chave files totalmente preenchida (ou pelo menos uma que não possa ser preenchida a partir da chave files da trilha):

configlet sync --filepaths

(Observe que o configlet lint também produz um erro quando um exercício tem uma chave files ausente ou vazia.)

Para preencher valores vazios ou ausentes da chave files no nível do exercício de todos os Exercícios de Conceito e de Prática a partir dos padrões na chave files da trilha:

configlet sync --filepaths --update

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

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

Usando o sync ao adicionar um novo exercício a uma trilha

O comando sync é útil ao adicionar um novo exercício a uma trilha. Se você está adicionando um Exercício de Prática chamado foo que existe no problem-specifications, um fluxo de trabalho possível é:

1. Adicione manualmente uma entrada para o exercício foo no arquivo config.json da trilha. Isso torna o exercício visível para o configlet sync.
2. Execute configlet sync --docs --filepaths --metadata -uy -e foo para criar a documentação do exercício e um arquivo .meta/config.json inicial com os valores files, blurb e talvez source e source_url preenchidos.
3. Edite o arquivo .meta/config.json do exercício como quiser. Por exemplo, adicione você mesmo ao array authors.
4. Execute configlet sync --tests include -u -e foo para criar um arquivo .meta/tests.toml com todos os testes incluídos.
5. Veja esse arquivo .meta/tests.toml e adicione include = false a qualquer caso de teste que o exercício não vai implementar.
6. Implemente os testes do exercício para corresponder aos que estão incluídos no .meta/tests.toml.
7. Adicione os outros arquivos necessários.