Adicionar um exercício de prática

Este documento explica como adicionar um novo Exercício de Prática.

Escolher o exercício

A forma mais simples de ver que Exercícios de Prática ainda não foram implementados é ir à página de construção do percurso (por exemplo, https://exercism.org/tracks/csharp/build) e ver a secção «Exercícios de Prática».

Caution

Os dados da página de construção são atualizados uma vez por dia.

Criar a estrutura do exercício

Podes criar rapidamente a estrutura de um novo Exercício de Prática executando o script bin/add-practice-exercise (código-fonte) a partir do diretório raiz do percurso:

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

Opcionalmente, também podes especificar a dificuldade do exercício (com -d) e/ou o nome de utilizador do autor no GitHub (com -a):

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

Se estiveres a trabalhar num repositório de um percurso que não tenha este ficheiro, podes copiá-los para o teu repositório usando a ligação para o código-fonte acima.

Implementar o exercício

Depois de criados os ficheiros da estrutura base, terás de:

  • Adicionar testes ao ficheiro de testes
  • Adicionar uma implementação de exemplo
  • Definir o conteúdo do ficheiro stub
  • No ficheiro .meta/config.json do exercício:
    • Adicionar à chave authors o nome de utilizador no GitHub dos autores do exercício
  • No ficheiro config.json do percurso:
    • Verificar/atualizar a dificuldade do exercício
    • Adicionar conceitos à chave practices (só é necessário quando o percurso tem exercícios de conceito)
    • Adicionar conceitos à chave prerequisites (só é necessário quando o percurso tem exercícios de conceito)

Adicionar testes

Uma parte essencial de adicionar um exercício é adicionar testes. De um modo geral, há duas opções quando adicionas testes a um Exercício de Prática:

  1. Implementar os testes de raiz, usando os casos de teste do ficheiro canonical-data.json do exercício, disponíveis no repositório problem-specifications.
  2. Adaptar os testes da implementação de outro percurso (sugestão: vai a https://exercism.org/exercises/<slug> para veres que percursos já implementaram um determinado exercício).

A segunda opção pode ser especialmente apelativa, porque dá resultados rapidamente. Tem em atenção, no entanto, que deves ajustar a implementação para se adequar o melhor possível ao teu percurso. Por exemplo, alguns percursos não usam classes e trabalham apenas com funções. Se, no entanto, o teu percurso costuma trabalhar com objetos, deves adaptar a implementação ao que melhor se adequa.

Note

Alguns percursos usam um gerador de testes para (re)gerar automaticamente o(s) ficheiro(s) de testes de um exercício. Consulta a documentação do percurso para ver se existe um gerador de testes e, em caso afirmativo, como o usar.

Adicionar uma implementação de exemplo

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

Note

O código não tem de ser idiomático; só tem de passar nos testes.

Podes verificar que a implementação de exemplo passa em todos os testes executando o script bin/verify-exercises (código-fonte) a partir do diretório raiz do percurso:

bin/verify-exercises <exercise-slug>

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

Note

Se estiveres a trabalhar num repositório de um percurso que não tenha este ficheiro, podes copiá-los para o teu repositório usando a ligação para o código-fonte acima.

Advanced

Nos bastidores, o script bin/verify-exercises faz várias coisas:

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

Adicionar ficheiro(s) stub

O(s) ficheiro(s) de implementação stub fornecem um ponto de partida para os estudantes.

Recomendamos que os ficheiros stub tenham a quantidade mínima de código para que:

  • O estudante possa começar imediatamente a implementar a lógica para passar nos testes
  • O estudante não seja confrontado com erros de sintaxe «estranhos»

Na prática, isto significa definir as funções/métodos que são testados pelo conjunto de testes. Os percursos são livres de organizar este código como quiserem, desde que garantam que o código stub falha inicialmente todos os testes.

Exemplos

Python:

def two_fer(name):
    pass

Kotlin:

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

Executar o linter no exercício

O passo final é executar o linter para verificar se os ficheiros (de configuração) do percurso estão devidamente estruturados, tanto a nível sintático como semântico.

Primeiro, certifica-te de que tens a versão mais recente do configlet executando:

bin/fetch-configlet

Depois, executa o linter com:

bin/configlet lint

Usa a saída para verificar que está tudo bem.

Submeter um Pull Request

Quando estiver tudo bem, podes submeter um Pull Request ao repositório do percurso.

Antes de submeteres, lê o Guia de Pull Requests para Contribuidores e o Guia de Pull Requests.

Garante que a descrição do PR indica o exercício que está a ser adicionado.