Criando trilhas

Uma trilha é composta de muitas partes diferentes.

Metadados

A configuração e os metadados da trilha são especificados no arquivo config.json. Nele estão listados os exercícios, os conceitos, as configurações do editor e muito mais. Confira a documentação do config.json.

Conceitos

Todos os exercícios de conceito e de prática de uma trilha envolvem conceitos. Esses conceitos são entidades próprias e independentes. Confira a documentação para saber mais.

Os conceitos ensinados nos exercícios de conceito da trilha formam um currículo. O currículo é mostrado aos estudantes como um mapa de conceitos. Confira a documentação do mapa de conceitos para saber como montar o mapa de conceitos de um currículo.

Para saber mais sobre como projetar um currículo, confira a documentação do currículo.

Exercícios

As trilhas têm dois tipos de exercícios:

  • Exercícios de conceito: são projetados para ensinar um ou mais conceitos a um estudante. Confira a documentação para saber mais.
  • Exercícios de prática: são projetados para praticar os conceitos aprendidos. Confira a documentação para saber mais.

Aprofunde-se

Cada exercício tem uma seção opcional Aprofunde-se, que pode conter:

  • Abordagens: diferentes formas de resolver o exercício
  • Artigos: descrevem aspectos interessantes do exercício
  • Vídeos da comunidade: vídeos que mostram o exercício, geralmente com alguém resolvendo o exercício do zero

Arquivos compartilhados

Alguns arquivos não são específicos de exercícios individuais, mas se aplicam a todos os exercícios. Confira a documentação para saber mais.

Documentação

Cada trilha tem alguns arquivos de documentação obrigatórios. Confira a documentação para saber mais.

Widgets

Algumas partes da trilha podem ser exibidas em widgets.

Guia de estilo

Todos os documentos devem seguir o guia de estilo. Documentos Markdown também devem seguir os nossos padrões de Markdown.

Exemplo

csharp
├── config
|   ├── exercise_readme.go.tmpl
|   └── maintainers.json
├── docs
|   ├── ABOUT.md
|   ├── INSTALLATION.md
|   ├── LEARNING.md
|   ├── RESOURCES.md
|   └── TESTS.md
├── concepts
|   └── numbers
|       ├── about.md
|       ├── introduction.md
|       └── links.json
└── exercises
|   ├── concept
|   |   └── cars-assemble
|   |       ├── .docs
|   |       |   ├── hints.md
|   |       |   ├── introduction.md
|   |       |   └── instructions.md
|   |       ├── .meta
|   |       |   ├── config.json
|   |       |   ├── design.md
|   |       |   └── Exemplar.cs (track-specific)
|   |       ├── CarsAssemble.cs (track-specific)
|   |       ├── CarsAssemble.csproj (track-specific)
|   |       └── CarsAssembleTests.cs (track-specific)
|   ├── practice
|   |   └── leap
|   |       └── .docs
|   |       |   └── instructions.md
|   |       └── .meta
|   |       |   ├── config.json
|   |       |   └── Example.cs (track-specific)
|   |       ├── Leap.cs (track-specific)
|   |       ├── Leap.csproj (track-specific)
|   |       └── LeapTests.cs (track-specific)
|   └── shared
|       └── .docs
|           ├── debug.md
|           ├── help.md
|           └── tests.md
└── config.json

Manutenção

Permissões do repositório

Cada trilha recebe (automaticamente) uma categoria de manutenção, que determina as permissões do mantenedor da trilha no repositório do GitHub.

Evitar disparar execuções de testes desnecessárias

Quando você faz merge de um PR de trilha que mexe em um exercício, isso faz com que todas as últimas iterações publicadas das soluções dos estudantes sejam testadas de novo. Para exercícios populares, essa é uma operação muito cara (70.000 execuções de testes no Hello World de Python, em um caso extremo!).

Recomendamos que você tente evitar fazer isso sem necessidade.

As soluções não serão testadas de novo se o commit mesclado:

  • mexer apenas em arquivos .docs ou .meta, ou em outros arquivos com os quais os usuários não interagem
  • ou contiver [no important files changed] no corpo do commit.

As soluções serão testadas de novo se o commit mesclado:

  • não tiver [no important files changed] no corpo do commit
  • e mexer em um dos seguintes arquivos de um exercício (conforme especificado no arquivo .meta/config.json dele):
    • arquivos de teste
    • arquivos do editor
    • arquivos de invalidação

Alguns exemplos:

  • Python#3423: só mexe em documentação, então nenhum teste foi executado
  • Python#3437: foi mesclado com [no important files changed] adicionado, então nenhum teste foi executado
  • Csharp#2138: espaços em branco foram removidos dos testes. A palavra-chave não foi adicionada. Os testes foram executados de novo sem necessidade.