Agregar un ejercicio de práctica

Este documento explica cómo agregar un nuevo ejercicio de práctica.

Seleccionar el ejercicio

La forma más sencilla de ver qué ejercicios de práctica aún no se han implementado es entrar a la página de build del track (por ejemplo, https://exercism.org/tracks/csharp/build) y revisar la sección «Ejercicios de práctica».

Caution

Los datos de la página de build se actualizan una vez al día.

Generar el andamiaje del ejercicio

Puedes generar rápidamente el andamiaje de un nuevo ejercicio de práctica ejecutando el script bin/add-practice-exercise (código fuente) desde el directorio raíz del track:

bin/add-practice-exercise <exercise-slug>

De manera opcional, también puedes especificar la dificultad del ejercicio (con -d) y/o el nombre de usuario de GitHub de quien lo creó (con -a):

bin/add-practice-exercise -d 3 -a foobar <exercise-slug>
Note

Si trabajas en el repositorio de un track que no tiene este archivo, puedes copiarlo a tu repositorio usando el enlace de código fuente de arriba.

Implementar el ejercicio

Una vez que se hayan creado los archivos del andamiaje, tendrás que:

  • Agregar tests al archivo de tests
  • Agregar una implementación de ejemplo
  • Definir el contenido de los archivos stub
  • En el archivo .meta/config.json del ejercicio:
    • Agregar el nombre de usuario de GitHub de quienes crearon el ejercicio a la clave authors
  • En el archivo config.json del track:
    • Revisar o actualizar la dificultad del ejercicio
    • Agregar conceptos a la clave practices (solo se necesita cuando el track tiene ejercicios de concepto)
    • Agregar conceptos a la clave prerequisites (solo se necesita cuando el track tiene ejercicios de concepto)

Agregar tests

Una parte fundamental de agregar un ejercicio es agregar tests. A grandes rasgos, hay dos opciones para agregar tests a un ejercicio de práctica:

  1. Implementar los tests desde cero, usando los casos de prueba del archivo canonical-data.json del ejercicio, que se encuentra en el repositorio problem-specifications.
  2. Portar los tests desde la implementación de otro track (consejo: ve a https://exercism.org/exercises/<slug> para ver un resumen de qué tracks han implementado un ejercicio en concreto).

La segunda opción puede resultar especialmente atractiva, porque te da resultados rápido. Ten en cuenta, sin embargo, que conviene ajustar la implementación para que encaje lo mejor posible en tu track. Por ejemplo, algunos tracks no usan clases y solo trabajan con funciones. Pero si tu track normalmente trabaja con objetos, deberías adaptar la implementación a lo que mejor se ajuste a tu track.

Note

Algunos tracks usan un generador de tests para (re)generar automáticamente el o los archivos de tests de un ejercicio. Revisa la documentación del track para ver si hay un generador de tests y, de haberlo, cómo usarlo.

Agregar una implementación de ejemplo

Para garantizar que sea posible escribir código que pase los tests, hay que agregar una implementación de ejemplo:

Note

El código no tiene que ser idiomático; basta con que pase los tests.

Puedes verificar que la implementación de ejemplo pase todos los tests ejecutando el script bin/verify-exercises (código fuente) desde el directorio raíz del track:

bin/verify-exercises <exercise-slug>

Usa la salida para verificar que la implementación de ejemplo pase todos los tests.

Note

Si trabajas en el repositorio de un track que no tiene este archivo, puedes copiarlo a tu repositorio usando el enlace de código fuente de arriba.

Advanced

Por dentro, el script bin/verify-exercises hace varias cosas:

  • Copia el ejercicio a un directorio temporal
  • Sobrescribe el o los archivos stub con el o los archivos de la implementación de ejemplo
  • Si el archivo de tests tiene tests omitidos, se les quitará la omisión
  • Ejecuta los tests

Agregar archivo(s) stub

El o los archivos stub de la implementación les dan un punto de partida a los estudiantes.

Recomendamos que los archivos stub tengan la mínima cantidad de código posible, de modo que:

  • El estudiante pueda empezar de inmediato a implementar la lógica para pasar los tests
  • El estudiante no se encuentre con errores de sintaxis «raros»

En la práctica, esto significa definir las funciones o métodos que prueba la suite de tests. Cada track es libre de decidir cómo organiza este código, siempre que garantice que el código stub falle todos los tests al principio.

Ejemplos

Python:

def two_fer(name):
    pass

Kotlin:

fun twofer(name: String): String {
    TODO("Implement the function to complete the task")
}

Ejecutar el linter

El último paso es ejecutar el linter para comprobar que los archivos (de configuración) del track estén bien estructurados, tanto sintáctica como semánticamente.

Primero, asegúrate de tener la versión más reciente de configlet ejecutando:

bin/fetch-configlet

Luego ejecuta el linter con:

bin/configlet lint

Usa la salida para verificar que todo esté bien.

Enviar el Pull Request

Cuando todo esté bien, puedes enviar un Pull Request al repositorio del track.

Antes de enviarlo, lee la Guía de Pull Requests para colaboradores y la Guía de Pull Requests.

Asegúrate de que la descripción del PR incluya el ejercicio que se está agregando.