Adiciona o primeiro exercício

O primeiro exercício de cada percurso é um exercício muito simples de "Hello, World!".

O objetivo deste exercício é garantir rapidamente que está tudo ligado como deve ser. Isto confirma que o utilizador tem o ambiente de programação instalado corretamente, que sabe correr os testes e que consegue fazê-los passar. Além disso, no caso do cliente de linha de comandos do Exercism (CLI), garante também que o CLI está instalado e configurado corretamente e que o site entrega os ficheiros certos do exercício sem entregar artefactos desnecessários. Por último, garante que o utilizador está familiarizado com o ciclo de descarregar um exercício com o CLI, resolver um problema no seu ambiente de desenvolvimento local e submeter a solução de volta ao site.

Por outras palavras, ainda não se trata propriamente de aprender nada sobre a linguagem em si. O objetivo é algo extremamente simples.

Provavelmente, esta será também a parte mais difícil de configurar corretamente o repositório do percurso, uma vez que implementar um exercício envolve muitas peças em jogo.

Implementar o exercício

O exercício "Hello, World!" tem algumas regras especiais:

• É sempre o primeiro exercício de um percurso
• Todos os percursos têm de o implementar
• O ficheiro de testes tem apenas um teste
• O ficheiro stub contém uma implementação quase funcional, mas em vez de "Hello, World!" usa "Goodbye, Mars!"
• Não tem prerequisites
• Não tem practices

Determinar os caminhos dos ficheiros

O exercício "Hello, World!" (e, na verdade, todos os exercícios do Exercism) exige um conjunto específico de ficheiros:

• Documentação: explica ao estudante o que tem de fazer (pode ser gerada automaticamente).
• Metadados: fornecem ao Exercism alguns metadados sobre o exercício (podem ser gerados quase totalmente de forma automática).
• Conjunto de testes: verifica se uma solução está correta (específico do percurso).
• Implementação stub: fornece um ponto de partida aos estudantes (específica do percurso).
• Implementação de exemplo: fornece uma implementação de exemplo que passa todos os testes (específica do percurso).
• Ficheiros adicionais: garantem que os testes podem ser executados (específicos do percurso, opcionais).

Antes de podermos criar o exercício "Hello, World!", tens de tomar algumas decisões sobre os nomes e os caminhos dos ficheiros específicos do percurso (conjunto de testes, implementação stub, implementação de exemplo e eventuais ficheiros adicionais).

A regra geral é usar nomes idiomáticos para a linguagem. Quando não houver preferências fortes, dá preferência a estruturas de diretórios menos profundas. A implementação de exemplo tem de ser identificável pelo script de CI, por isso é aconselhável escolher um nome base genérico que todos os exercícios possam usar, por exemplo example, sample ou reference-solution.

Configurar os caminhos dos ficheiros

Depois de escolheres os caminhos dos ficheiros específicos do percurso, deves configurá-los na chave files do ficheiro config.json da raiz. A chave files serve de modelo para todos os exercícios, o que permite que qualquer ferramenta (algumas das quais vamos usar já a seguir) saiba onde procurar os ficheiros. Podes usar vários placeholders para configurar facilmente o slug do exercício (hello-world, neste caso).

Exemplo

Se o teu percurso usa PascalCase nos nomes dos ficheiros, a chave files pode ter este aspeto:

"files": {
  "solution": [
    "%{pascal_slug}.cs"
  ],
  "test": [
    "%{pascal_slug}Tests.cs"
  ],
  "example": [
    ".meta/Example.cs"
  ]
}

Para mais informações, consulta a documentação da chave files.

Criar os ficheiros

Depois de especificares os modelos de caminhos de ficheiros, podes criar rapidamente os ficheiros do exercício "Hello, World!" executando os seguintes comandos a partir do diretório raiz do percurso:

bin/fetch-configlet
bin/configlet create --practice-exercise hello-world

Definir o autor

Para que o site te apresente como autor do exercício, segue estes passos:

No ficheiro .meta/config.json do exercício:

• Adiciona o teu nome de utilizador do GitHub à chave authors

Para isto funcionar, tens de associar a tua conta do Exercism ao GitHub. Podes fazê-lo no site, na secção Integrações da página Definições.

Usar o script

Os repositórios de percurso mais recentes podem usar o script bin/add-practice-exercise (código-fonte) para adicionar novos exercícios:

bin/add-exercise -a <github_username> two-fer

Implementar o exercício

Depois de criados os ficheiros base, vais ter de:

• Adicionar testes ao ficheiro de testes
• Adicionar uma implementação de exemplo
• Definir o conteúdo do ficheiro stub

Adicionar os testes

Uma parte essencial de adicionar um exercício é adicionar testes. Grosso modo, há duas opções ao implementar um dos exercícios acima:

1. Implementar os testes de raiz, usando os casos de teste do canonical-data.json do exercício
2. Portar os testes da implementação de outro percurso (dica: vai a https://exercism.org/exercises/hello-world para veres uma visão geral de que percursos já implementaram um determinado exercício).

Para o exercício "Hello, World!", só haverá um caso de teste, por isso qualquer das opções serve.

Adicionar a implementação de exemplo

O ficheiro da implementação de exemplo deve conter o código necessário para resolver os testes.

Definir o stub

O ficheiro stub deve ter uma solução quase funcional para os testes, mas com o texto "Hello, World!" substituído por "Goodbye, Mars!". Dica: basta copiar, colar e modificar a solução de exemplo.

Atualizar o(s) autor(es) do exercício

Quando terminares o exercício, adiciona o teu nome de utilizador do GitHub ao array "authors" no ficheiro .meta/config.json do exercício. Assim garantimos que recebes o devido crédito por teres criado o exercício.

Linting

Para verificares se o exercício está configurado corretamente, podes usar a funcionalidade de linting integrada da ferramenta configlet.

O primeiro passo é descarregar a ferramenta configlet, para a qual criámos dois scripts:

• bin/fetch-configlet: executa este se usares *nix ou macOS
• bin/fetch-configlet.ps1: executa este se usares Windows

Executar um destes scripts a partir do diretório raiz do repositório do percurso descarrega o binário bin/configlet ou bin/configlet.exe, respetivamente.

Podes depois verificar se o exercício está correto executando bin/configlet lint.

The `tags` array is empty:
/path/to/track/config.json