Crear tracks

Un track consta de muchas partes diferentes.

Metadatos

La configuración y los metadatos del track se especifican en el fichero config.json. En él se enumeran los ejercicios, los conceptos, la configuración del editor y mucho más. Consulta la documentación de config.json.

Conceptos

Todos los ejercicios de concepto y de práctica de un track implican conceptos. Estos conceptos son entidades independientes en sí mismas. Consulta la documentación para obtener más información.

Los conceptos que se enseñan en los ejercicios de concepto del track forman un temario. El temario se muestra a los estudiantes como un mapa de conceptos. Consulta la documentación del mapa de conceptos para saber cómo crear el mapa de conceptos de un temario.

Para obtener más información sobre cómo diseñar un temario, consulta la documentación del temario.

Ejercicios

Los tracks tienen dos tipos de ejercicios:

  • Ejercicios de concepto: están diseñados para enseñar uno o más conceptos a un estudiante. Consulta la documentación para obtener más información.
  • Ejercicios de práctica: están diseñados para practicar los conceptos aprendidos. Consulta la documentación para obtener más información.

Dig deeper

Cada ejercicio tiene una sección opcional Dig Deeper que puede contener:

  • Enfoques: distintas formas de resolver el ejercicio
  • Artículos: describen aspectos interesantes del ejercicio
  • Vídeos de la comunidad: vídeos que muestran el ejercicio, normalmente con alguien que lo resuelve desde cero

Ficheros compartidos

Algunos ficheros no son específicos de cada ejercicio, sino que se aplican a todos los ejercicios. Consulta la documentación para obtener más información.

Documentación

Cada track tiene un par de ficheros de documentación obligatorios. Consulta la documentación para obtener más información.

Widgets

Algunas partes del track se pueden mostrar en widgets.

Guía de estilo

Todos los documentos deben seguir la guía de estilo. Los documentos Markdown también deben seguir nuestros estándares de Markdown.

Ejemplo

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

Mantenimiento

Permisos del repositorio

A cada track se le asigna (automáticamente) una categoría de mantenimiento, que determina los permisos del repositorio de GitHub del mantenedor del track.

Cómo evitar provocar ejecuciones innecesarias de tests

Cuando fusionas un PR del track que afecta a un ejercicio, se vuelven a ejecutar los tests de todas las últimas iteraciones publicadas de las soluciones de los estudiantes. En los ejercicios populares, esta es una operación muy costosa (¡70.000 ejecuciones de tests para el Hello World de Python como caso extremo!).

Te animamos a intentar evitar hacerlo sin necesidad.

Las soluciones no se volverán a testear si el commit fusionado cumple alguna de estas condiciones:

  • solo modifica ficheros .docs o .meta, u otros ficheros con los que los usuarios no interactúan
  • o incluye [no important files changed] en el cuerpo del commit.

Las soluciones sí se volverán a testear si el commit fusionado cumple las dos condiciones siguientes:

  • no incluye [no important files changed] en el cuerpo del commit
  • y modifica uno de los siguientes ficheros de un ejercicio (según lo indicado en su fichero .meta/config.json):
    • ficheros de tests
    • ficheros del editor
    • ficheros de invalidación

Algunos ejemplos:

  • Python#3423: Solo modifica la documentación, así que no se ejecutó ningún test
  • Python#3437: Se fusionó con [no important files changed] añadido, así que no se ejecutó ningún test
  • Csharp#2138: Se eliminaron los espacios en blanco de los tests. La palabra clave no se añadió. Los tests se volvieron a ejecutar sin necesidad.