Creare i track

Un track è composto da molte parti diverse.

Metadati

La configurazione e i metadati di un track sono specificati nel file config.json. Il file elenca gli esercizi del track, i concetti, le impostazioni dell'editor e molto altro. Dai un'occhiata alla documentazione di config.json.

Concetti

Tutti gli esercizi sui concetti e gli esercizi di pratica di un track coinvolgono dei concetti. Questi concetti sono entità a sé stanti. Consulta la documentazione per maggiori informazioni.

I concetti insegnati negli esercizi sui concetti di un track formano un syllabus. Il syllabus viene mostrato agli studenti come una mappa concettuale. Consulta la documentazione sulla mappa concettuale per scoprire come costruire la mappa concettuale di un syllabus.

Per maggiori informazioni su come progettare un syllabus, consulta la documentazione sul syllabus.

Esercizi

I track hanno due tipi di esercizi:

  • Esercizi sui concetti: sono progettati per insegnare uno o più concetti a uno studente. Consulta la documentazione per maggiori informazioni.
  • Esercizi di pratica: sono progettati per esercitarsi sui concetti appresi. Consulta la documentazione per maggiori informazioni.

Approfondimenti

Ogni esercizio ha una sezione "Approfondimenti" opzionale, che può contenere:

  • Approcci: modi diversi in cui l'esercizio può essere risolto
  • Articoli: descrivono aspetti interessanti dell'esercizio
  • Video della community: video che mostrano l'esercizio, di solito con qualcuno che lo risolve da zero

File condivisi

Alcuni file non sono specifici dei singoli esercizi, ma si applicano a tutti gli esercizi. Consulta la documentazione per maggiori informazioni.

Documentazione

Ogni track ha un paio di file di documentazione obbligatori. Consulta la documentazione per maggiori informazioni.

Widget

Alcune parti del track possono essere visualizzate nei widget.

Guida di stile

Tutti i documenti dovrebbero seguire la guida di stile. Anche i documenti Markdown dovrebbero seguire i nostri standard Markdown.

Esempio

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

Manutenzione

Permessi del repo

A ogni track viene assegnata (automaticamente) una categoria di manutenzione, che determina i permessi del repo GitHub del maintainer del track.

Evitare di innescare esecuzioni di test non necessarie

Quando fai il merge di una PR del track che tocca un esercizio, si innesca un nuovo test di tutte le ultime iterazioni pubblicate delle soluzioni degli studenti. Per gli esercizi più popolari, si tratta di un'operazione molto onerosa (nel caso estremo, 70.000 esecuzioni di test per Hello World in Python!).

Ti invitiamo a cercare di evitare di farlo inutilmente.

Le soluzioni non verranno testate di nuovo se il commit unito:

  • tocca solo file .docs o .meta, o altri file con cui gli utenti non interagiscono
  • oppure contiene [no important files changed] nel corpo del commit.

Le soluzioni verranno testate di nuovo se il commit unito soddisfa entrambe queste condizioni:

  • non contiene [no important files changed] nel corpo del commit
  • e tocca uno dei seguenti file di un esercizio (come specificato nel suo file .meta/config.json):
    • file di test
    • file dell'editor
    • file di invalidazione

Alcuni esempi:

  • Python#3423: tocca solo la documentazione, quindi non sono stati eseguiti test
  • Python#3437: è stato unito con l'aggiunta di [no important files changed], quindi non sono stati eseguiti test
  • Csharp#2138: sono stati rimossi gli spazi bianchi dai test. La parola chiave non è stata aggiunta. I test sono stati rieseguiti inutilmente.