Building Tracks

A track consists of many different parts.

Metadata

The track's configuration and metadata are specified in the config.json file. It lists the track's exercises, concepts, editor settings, and much more. Checkout the config.json documentation.

Concepts

All concept and practices exercises of a track involve concepts. These concepts are separate entities by themselves. Check the documentation for more information.

The concepts taught in the track's concept exercises form a syllabus. The syllabus is shown to students as a concept map. Check the concept map documentation to learn about building out the concept map for a syllabus.

For more information on how to design a syllabus, check the syllabus documentation.

Exercises

Tracks have two types of exercises:

  • Concept exercises: they are designed to teach one or more concepts to a student. Check the documentation for more information.
  • Practice exercises: they are designed to practice learned concepts. Check the documentation for more information.

Dig deeper

Each exercise has an optional Dig Deeper section that can contain:

  • Approaches: different ways in which the exercise can be solved
  • Articles: describe interesting aspects of the exercise
  • Community videos: videos that showcase the exercise, usually by having someone solve the exercise from scratch

Shared files

Some files are not specific to individual exercises, but are instead applicable to all exercises. Check the documentation for more information.

Docs

Each track has a couple of required documentation files. Check the documentation for more information.

Widgets

Some parts of the track can be displayed in widgets.

Style guide

All documents should adhere to the style guide. Markdown documents should also adhere to our Markdown standards.

Example

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

Maintenance

Repo permissions

Each track is (automatically) assigned a maintenance category, which determines the track maintainer's GitHub repo permissions.

Avoiding triggering unnecessary test runs

When you merge a track PR that touches an exercise, it triggers all the latest published iteration of students' solutions to be re-tested. For popular exercises, this is a very expensive operation (70,000 test runs for Python Hello World as an extreme!).

We encourage you to try and avoid doing this unnecessarily.

Solutions will not be retested if the merged commit either:

  • only touches .docs or .meta files, or other files that users don't interact with
  • or contains [no important files changed] in the commit body.

Solutions will be re-tested if the merged commit both:

  • lacks [no important files changed] in the commit body
  • and touches one of the following files for an exercise (as specified in its .meta/config.json file):
    • test files
    • editor files
    • invalidator files

Some examples:

  • Python#3423: Only touches docs so no tests were run
  • Python#3437: Was merged with [no important files changed] added, so no tests were run
  • Csharp#2138: Whitespace was removed from tests. The keyword was not added. Tests were re-run unnecessarily.