Añadir un ejercicio de práctica

Este documento explica cómo añadir un nuevo ejercicio de práctica.

Seleccionar el ejercicio

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

Caution

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

Generar la estructura del ejercicio

Puedes generar rápidamente la estructura 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 forma opcional, también puedes indicar la dificultad del ejercicio (con -d), el nombre de usuario de GitHub del autor (con -a) o ambos:

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

Si trabajas en el repositorio de un track que no tiene este fichero, no dudes en copiarlos a tu repositorio usando el enlace al código fuente de arriba.

Implementar el ejercicio

Una vez creados los ficheros generados, tendrás que:

  • Añadir tests al fichero de tests
  • Añadir una implementación de ejemplo
  • Definir el contenido del fichero stub
  • En el fichero .meta/config.json del ejercicio:
    • Añadir el nombre de usuario de GitHub de los autores del ejercicio a la clave authors
  • En el fichero config.json del track:
    • Comprobar o actualizar la dificultad del ejercicio
    • Añadir conceptos a la clave practices (solo es necesario cuando el track tiene ejercicios de concepto)
    • Añadir conceptos a la clave prerequisites (solo es necesario cuando el track tiene ejercicios de concepto)

Añadir tests

Una parte fundamental de añadir un ejercicio es añadir tests. A grandes rasgos, hay dos opciones a la hora de añadir tests a un ejercicio de práctica:

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

La segunda opción puede resultar especialmente atractiva, ya que te da resultados rápidos. Ten en cuenta, no obstante, que debes adaptar la implementación para que encaje lo mejor posible con tu track. Por ejemplo, algunos tracks no usan clases y solo trabajan con funciones. Si tu track suele trabajar con objetos, deberías adaptar la implementación a lo que mejor encaje con tu track.

Note

Algunos tracks usan un generador de tests para generar (o regenerar) automáticamente el fichero o los ficheros de tests de un ejercicio. Consulta la documentación del track para ver si hay un generador de tests y, en tal caso, cómo usarlo.

Añadir una implementación de ejemplo

Para asegurarte de que es posible escribir código que pase los tests, hay que añadir una implementación de ejemplo.

Note

El código no tiene que ser idiomático; solo tiene que pasar los tests.

Puedes comprobar que la implementación de ejemplo pasa 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 comprobar que la implementación de ejemplo pasa todos los tests.

Note

Si trabajas en el repositorio de un track que no tiene este fichero, no dudes en copiarlos a tu repositorio usando el enlace al código fuente de arriba.

Advanced

Entre bastidores, el script bin/verify-exercises hace varias cosas:

  • Copia el ejercicio a un directorio temporal
  • Sobrescribe el fichero o los ficheros stub con el fichero o los ficheros de la implementación de ejemplo
  • Si el fichero de tests contiene tests omitidos, se «reactivarán»
  • Ejecuta los tests

Añadir el fichero o los ficheros stub

El fichero o los ficheros de implementación stub proporcionan un punto de partida para los estudiantes.

Recomendamos que los ficheros stub contengan la cantidad mínima de código para 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 se comprueban en la suite de tests. Cada track es libre de organizar este código como quiera, siempre que se asegure de que el código stub falla inicialmente todos los tests.

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 ficheros (de configuración) del track están bien estructurados, tanto sintáctica como semánticamente.

En primer lugar, asegúrate de tener la última versión de configlet ejecutando:

bin/fetch-configlet

A continuación, ejecuta el linter con:

bin/configlet lint

Usa la salida para comprobar que todo está en orden.

Enviar un Pull Request

Cuando todo esté en orden, 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 añade.