Construir percursos

Um percurso é composto por várias partes diferentes.

Metadados

A configuração e os metadados do percurso são especificados no ficheiro config.json. Este ficheiro lista os exercícios, os conceitos, as definições do editor do percurso e muito mais. Consulta a documentação do config.json.

Conceitos

Todos os exercícios de conceito e de prática de um percurso envolvem conceitos. Estes conceitos são entidades independentes entre si. Consulta a documentação para mais informações.

Os conceitos ensinados nos exercícios de conceito do percurso formam um plano de estudos. O plano de estudos é apresentado aos estudantes como um mapa de conceitos. Consulta a documentação do mapa de conceitos para saberes como construir o mapa de conceitos de um plano de estudos.

Para mais informações sobre como conceber um plano de estudos, consulta a documentação do plano de estudos.

Exercícios

Os percursos têm dois tipos de exercícios:

  • Exercícios de conceito: destinam-se a ensinar um ou mais conceitos a um estudante. Consulta a documentação para mais informações.
  • Exercícios de prática: destinam-se a praticar os conceitos aprendidos. Consulta a documentação para mais informações.

Ir mais fundo

Cada exercício tem uma secção opcional, Ir mais fundo, que pode conter:

  • Abordagens: diferentes formas de resolver o exercício
  • Artigos: descrevem aspetos interessantes do exercício
  • Vídeos da comunidade: vídeos que mostram o exercício, normalmente com alguém a resolvê-lo de raiz

Ficheiros partilhados

Alguns ficheiros não são específicos de cada exercício, mas aplicam-se a todos os exercícios. Consulta a documentação para mais informações.

Documentação

Cada percurso tem alguns ficheiros de documentação obrigatórios. Consulta a documentação para mais informações.

Widgets

Algumas partes do percurso podem ser apresentadas em widgets.

Guia de estilo

Todos os documentos devem seguir o guia de estilo. Os documentos Markdown devem também seguir as nossas normas 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

A cada percurso é atribuída (automaticamente) uma categoria de manutenção, que determina as permissões do repositório GitHub do responsável pelo percurso.

Evitar desencadear execuções de testes desnecessárias

Quando fazes merge de um PR do percurso que mexe num exercício, isso faz com que a última iteração publicada de todas as soluções dos estudantes volte a ser testada. Para exercícios populares, esta é uma operação muito dispendiosa (70 000 execuções de testes no Hello World de Python, no extremo!).

Encorajamos-te a tentar evitar fazê-lo desnecessariamente.

As soluções não voltam a ser testadas se o commit integrado:

  • apenas mexer em ficheiros .docs ou .meta, ou noutros ficheiros com que os utilizadores não interagem
  • ou contiver [no important files changed] no corpo do commit.

As soluções voltam a ser testadas se o commit integrado:

  • não tiver [no important files changed] no corpo do commit
  • e mexer num dos seguintes ficheiros de um exercício (tal como especificado no seu ficheiro .meta/config.json):
    • ficheiros de testes
    • ficheiros do editor
    • ficheiros de invalidação

Alguns exemplos:

  • Python#3423: só mexe em documentação, por isso não foram executados testes
  • Python#3437: foi integrado com [no important files changed] adicionado, por isso não foram executados testes
  • Csharp#2138: removeu-se espaço em branco dos testes. A palavra-chave não foi adicionada. Os testes voltaram a ser executados sem necessidade.