Adicionar um exercício de prática

Este documento explica como adicionar um novo exercício de prática.

Escolha o exercício

A maneira mais simples de ver quais exercícios de prática ainda não foram implementados é acessar a página de build da track (por exemplo, https://exercism.org/tracks/csharp/build) e conferir a seção "Practice Exercises".

Caution

Os dados na página de build são atualizados uma vez por dia.

Crie a estrutura inicial do exercício

Você pode criar rapidamente a estrutura inicial de um novo exercício de prática rodando o script bin/add-practice-exercise (fonte) a partir do diretório raiz da track:

bin/add-practice-exercise <exercise-slug>

Opcionalmente, você também pode informar a dificuldade do exercício (com -d) e/ou o nome de usuário no GitHub de quem escreveu o exercício (com -a):

bin/add-practice-exercise -d 3 -a foobar <exercise-slug>
Note

Se você estiver trabalhando em um repositório de track sem esse arquivo, fique à vontade para copiá-lo para o seu repositório usando o link da fonte acima.

Implemente o exercício

Depois que os arquivos da estrutura inicial forem criados, você vai precisar:

  • Adicionar testes ao arquivo de testes
  • Adicionar uma implementação de exemplo
  • Definir o conteúdo do arquivo stub
  • No arquivo .meta/config.json do exercício:
    • Adicionar o nome de usuário no GitHub de quem escreveu o exercício à chave authors
  • No arquivo config.json da track:
    • Verificar/atualizar a dificuldade do exercício
    • Adicionar conceitos à chave practices (obrigatório apenas quando a track tem exercícios de conceito)
    • Adicionar conceitos à chave prerequisites (obrigatório apenas quando a track tem exercícios de conceito)

Adicione testes

Uma parte essencial de adicionar um exercício é adicionar testes. De modo geral, há duas opções ao adicionar testes para um exercício de prática:

  1. Implementar os testes do zero, usando os casos de teste do arquivo canonical-data.json do exercício, como encontrado no repositório problem-specifications.
  2. Portar os testes da implementação de outra track (dica: acesse https://exercism.org/exercises/<slug> para ver quais tracks já implementaram um exercício específico).

A segunda opção pode ser especialmente atraente, pois dá resultados rápido. Lembre-se, porém, de que você deve adaptar a implementação para que ela se encaixe o melhor possível na sua track. Por exemplo, algumas tracks não usam classes e trabalham apenas com funções. Mas, se a sua track costuma trabalhar com objetos, adapte a implementação ao que se encaixa melhor nela.

Note

Algumas tracks usam um gerador de testes para (re)gerar automaticamente o(s) arquivo(s) de teste de um exercício. Confira a documentação da track para ver se existe um gerador de testes e, se existir, como usá-lo.

Adicione uma implementação de exemplo

Para garantir que é possível escrever um código que passe nos testes, é preciso adicionar uma implementação de exemplo.

Note

O código não precisa ser idiomático, só precisa passar nos testes.

Você pode verificar se a implementação de exemplo passa em todos os testes rodando o script bin/verify-exercises (fonte) a partir do diretório raiz da track:

bin/verify-exercises <exercise-slug>

Use a saída para confirmar que a implementação de exemplo passa em todos os testes.

Note

Se você estiver trabalhando em um repositório de track sem esse arquivo, fique à vontade para copiá-lo para o seu repositório usando o link da fonte acima.

Advanced

Por baixo dos panos, o script bin/verify-exercises faz várias coisas:

  • Copia o exercício para um diretório temporário
  • Substitui o(s) arquivo(s) stub pelo(s) arquivo(s) da implementação de exemplo
  • Se o arquivo de testes tiver testes marcados como ignorados, eles passarão a ser executados
  • Roda os testes

Adicione o(s) arquivo(s) stub

O(s) arquivo(s) de implementação stub servem como ponto de partida para os estudantes.

Recomendamos que os arquivos stub tenham a quantidade mínima de código de modo que:

  • O estudante possa começar a implementar imediatamente a lógica para passar nos testes
  • O estudante não se depare com erros de sintaxe "estranhos"

Na prática, isso significa definir as funções/métodos que a suíte de testes testa. As tracks têm liberdade para organizar esse código como quiserem, desde que garantam que o código stub inicialmente falhe em todos os testes.

Exemplos

Python:

def two_fer(name):
    pass

Kotlin:

fun twofer(name: String): String {
    TODO("Implement the function to complete the task")
}

Rode o lint no exercício

O passo final é rodar o linter para verificar se os arquivos (de configuração) da track estão estruturados corretamente, tanto sintática quanto semanticamente.

Primeiro, certifique-se de que você tem a versão mais recente do configlet rodando:

bin/fetch-configlet

Depois, rode o linter com:

bin/configlet lint

Use a saída para confirmar que está tudo certo.

Envie um Pull Request

Quando estiver tudo certo, você pode enviar um Pull Request para o repositório da track.

Antes de enviar, leia o Guia de Pull Request para contribuidores e o Guia de Pull Requests.

Garanta que a descrição do PR liste o exercício que está sendo adicionado.