Añade el primer ejercicio

El primer ejercicio de cada track es un ejercicio «Hello, World!» muy sencillo.

El objetivo de este ejercicio es comprobar rápidamente que todo está conectado correctamente. Esto confirmará que el usuario tiene instalado correctamente el entorno de programación, que sabe cómo ejecutar las pruebas y que es capaz de hacer que pasen. Además, en el caso del cliente de línea de comandos de Exercism (CLI) también garantiza que tiene la CLI instalada y configurada correctamente, y que el sitio entrega los ficheros correctos para el ejercicio sin enviar artefactos innecesarios. Por último, garantiza que el usuario conoce el ciclo de descargar un ejercicio con la CLI, resolver un problema en su entorno de desarrollo local y enviar su solución de vuelta al sitio.

En otras palabras, todavía no se trata realmente de aprender nada sobre el lenguaje en sí. Buscamos algo realmente sencillo.

Es probable que también sea la parte más difícil de configurar bien el repositorio del track, ya que en la implementación de un ejercicio intervienen muchas piezas.

Implementación del ejercicio

El ejercicio «Hello, World!» tiene algunas reglas especiales:

• Siempre es el primer ejercicio de un track
• Cada track debe implementarlo
• El fichero de pruebas tiene una sola prueba
• El fichero stub contiene una implementación casi funcional, pero en lugar de «Hello, World!» usa «Goodbye, Mars!»
• No tiene prerequisites
• No tiene practices

Determinar las rutas de los ficheros

El ejercicio «Hello, World!» (y, de hecho, todos los ejercicios de Exercism) requiere un conjunto específico de ficheros:

• Documentación: explica al estudiante lo que tiene que hacer (se puede generar automáticamente).
• Metadatos: proporciona a Exercism ciertos metadatos sobre el ejercicio (en su mayoría se pueden generar automáticamente).
• Suite de pruebas: verifica que la solución es correcta (específica del track).
• Implementación stub: proporciona un punto de partida para los estudiantes (específica del track).
• Implementación de ejemplo: proporciona una implementación de ejemplo que pasa todas las pruebas (específica del track).
• Ficheros adicionales: garantizan que las pruebas puedan ejecutarse (específicos del track, opcionales).

Antes de crear el ejercicio «Hello, World!», tienes que tomar algunas decisiones sobre los nombres y las rutas de los ficheros específicos del track (suite de pruebas, implementación stub, implementación de ejemplo y los ficheros adicionales que haya).

Como norma general, usa nombres que sean idiomáticos para el lenguaje. Cuando no haya preferencias claras, opta por estructuras de directorios poco profundas. El script de CI tiene que poder identificar la implementación de ejemplo, así que conviene elegir un nombre base genérico que puedan usar todos los ejercicios, por ejemplo, example, sample o reference-solution.

Configurar las rutas de los ficheros

Una vez elegidas las rutas de los ficheros específicas del track, debes configurarlas en la clave files del fichero config.json de la raíz. La clave files sirve como plantilla para todos los ejercicios, lo que permite que cualquier herramienta (algunas de las cuales usaremos enseguida) sepa dónde buscar los ficheros. Puedes usar varios marcadores de posición para configurar fácilmente el slug del ejercicio (hello-world en este caso).

Ejemplo

Si tu track usa PascalCase para sus ficheros, la clave files podría tener este aspecto:

"files": {
  "solution": [
    "%{pascal_slug}.cs"
  ],
  "test": [
    "%{pascal_slug}Tests.cs"
  ],
  "example": [
    ".meta/Example.cs"
  ]
}

Para más información, consulta la documentación de la clave files.

Crear los ficheros

Una vez especificadas las plantillas de rutas de ficheros, puedes crear rápidamente la estructura de ficheros del ejercicio «Hello, World!» ejecutando los siguientes comandos desde el directorio raíz del track:

bin/fetch-configlet
bin/configlet create --practice-exercise hello-world

Establecer el autor

Para que el sitio web te incluya como autor del ejercicio, sigue estos pasos:

En el fichero .meta/config.json del ejercicio:

• Añade tu nombre de usuario de GitHub a la clave authors

Para que esto funcione, tendrás que vincular tu cuenta de Exercism a GitHub. Puedes hacerlo en el sitio web, en la sección Integrations de la página de configuración.

Usar el script

Los repositorios de track más recientes pueden usar el script bin/add-practice-exercise (código fuente) para añadir ejercicios nuevos:

bin/add-exercise -a <github_username> two-fer

Implementar el ejercicio

Una vez creados los ficheros de la estructura, tendrás que:

• Añadir pruebas al fichero de pruebas
• Añadir una implementación de ejemplo
• Definir el contenido del fichero stub

Añadir pruebas

Una parte fundamental de añadir un ejercicio es añadir pruebas. A grandes rasgos, hay dos opciones al implementar uno de los ejercicios anteriores:

1. Implementar las pruebas desde cero, usando los casos de prueba del canonical-data.json del ejercicio
2. Portar las pruebas desde la implementación de otro track (truco: ve a https://exercism.org/exercises/hello-world para ver qué tracks han implementado un ejercicio concreto).

Para el ejercicio «Hello, World!» solo habrá un caso de prueba, así que cualquiera de las dos opciones debería servir.

Añadir una implementación de ejemplo

El fichero de implementación de ejemplo debe contener el código necesario para resolver las pruebas.

Definir el stub

El fichero stub debe tener una solución casi funcional para las pruebas, pero con el texto «Hello, World!» sustituido por «Goodbye, Mars!». Truco: basta con copiar, pegar y modificar la solución de ejemplo.

Actualizar el autor o los autores del ejercicio

Cuando termines el ejercicio, añade tu nombre de usuario de GitHub al array "authors" del fichero .meta/config.json del ejercicio. Así nos aseguraremos de acreditarte correctamente como creador del ejercicio.

Linting

Para verificar que el ejercicio está configurado correctamente, puedes usar la funcionalidad de linting integrada de la herramienta configlet.

El primer paso es descargar la herramienta configlet, para lo cual hemos creado dos scripts:

• bin/fetch-configlet: ejecútalo si usas *nix o macOS
• bin/fetch-configlet.ps1: ejecútalo si usas Windows

Ejecutar uno de estos scripts desde el directorio raíz del repositorio del track descargará el binario bin/configlet o bin/configlet.exe, respectivamente.

A continuación, puedes comprobar que el ejercicio es correcto ejecutando bin/configlet lint.

The `tags` array is empty:
/path/to/track/config.json