configlet sync

Sincronizar los datos de los ejercicios con el repositorio problem-specifications

Un ejercicio de práctica de un track de Exercism se implementa a menudo a partir de una especificación del repositorio exercism/problem-specifications.

Exercism exige deliberadamente que cada ejercicio tenga su propia copia de determinados ficheros (como .docs/instructions.md), incluso cuando ese ejercicio ya existe en problem-specifications. Por eso configlet tiene un comando sync, que puede comprobar que esos ejercicios de práctica de un track están sincronizados con esa fuente de origen y puede actualizarlos cuando hay actualizaciones disponibles.

Hay tres tipos de datos que se pueden actualizar desde problem-specifications: documentación, metadatos y tests. También hay un tipo de datos que se puede rellenar desde el fichero config.json a nivel de track: las rutas de ficheros en los ficheros de configuración de los ejercicios.

Describimos cómo comprobar y actualizar estos tipos de datos en secciones individuales más abajo, pero, como resumen rápido:

  • configlet sync solo actúa sobre los ejercicios que existen en el fichero config.json a nivel de track. Por lo tanto, si estás implementando un ejercicio nuevo en un track y quieres añadir los ficheros iniciales con configlet sync, añade primero el ejercicio al fichero config.json a nivel de track. Si el ejercicio todavía no está listo para ser visible para el usuario, establece su status en wip.
  • Un configlet sync sin más no hace ningún cambio en el track y comprueba todos los tipos de datos de todos los ejercicios.
  • Para actuar sobre un subconjunto de tipos de datos, usa alguna combinación de las opciones --docs, --filepaths, --metadata y --tests.
  • Para actualizar los datos del track de forma interactiva, usa la opción --update.
  • Para actualizar la documentación, las rutas de ficheros y los metadatos del track de forma no interactiva, usa --update --yes.
  • Para incluir de forma no interactiva todos los tests que aún no se han visto de un ejercicio dado, usa, por ejemplo, --update --tests include --exercise prime-factors.
  • Para evitar descargar el repositorio problem-specifications, añade --offline --prob-specs-dir /path/to/local/problem-specifications
  • Ten en cuenta que configlet sync intenta mantener el orden de las claves en los ficheros .meta/config.json de los ejercicios cuando los actualiza. Para escribir estos ficheros en una forma canónica sin sincronizar, usa el comando configlet fmt. Sin embargo, configlet sync sí añade las claves obligatorias (authors, files, blurb) (posiblemente vacías) cuando faltan. Esto es menos «propio de un sync», pero más ergonómico: al implementar un ejercicio nuevo, puedes usar sync para crear un fichero .meta/config.json inicial.
  • configlet sync elimina las claves que no están en la especificación. Los pares clave/valor personalizados siguen siendo compatibles: deben escribirse dentro de un objeto JSON llamado custom.
  • El código de salida es 0 cuando todos los datos vistos están sincronizados al salir configlet, y 1 en caso contrario.

Ten en cuenta que en las versiones 4.0.0-alpha.34 y anteriores de configlet, el comando sync solo actuaba sobre los tests.

Uso

El comando sync se puede usar para comprobar o actualizar la documentación, los metadatos y los tests de los ejercicios de práctica a partir de «problem-specifications». También puede comprobar o rellenar los valores files que falten en los ejercicios de concepto y de práctica a partir del «config.json» del track.

configlet [global-options] sync [command-options]

Global options:
  -h, --help                   Show this help message and exit
      --version                Show this tool's version information and exit
  -t, --track-dir <dir>        Specify a track directory to use instead of the current directory
  -v, --verbosity <verbosity>  The verbosity of output. Allowed values: q[uiet], n[ormal], d[etailed]

Options for sync:
  -e, --exercise <slug>        Only operate on this exercise
  -p, --prob-specs-dir <dir>   Use this 'problem-specifications' directory, rather than cloning temporarily
  -o, --offline                Do not check that the directory specified by --prob-specs-dir is up to date
  -u, --update                 Prompt to update the seen data that are unsynced
  -y, --yes                    Auto-confirm prompts from --update for updating docs, filepaths, and metadata
      --docs                   Sync Practice Exercise '.docs/introduction.md' and '.docs/instructions.md' files
      --filepaths              Populate empty 'files' values in Concept/Practice exercise '.meta/config.json' files
      --metadata               Sync Practice Exercise '.meta/config.json' metadata values
      --tests [mode]           Sync Practice Exercise '.meta/tests.toml' files.
                               The mode value specifies how missing tests are handled when using --update.
                               Allowed values: c[hoose], i[nclude], e[xclude] (default: choose)

Documentación

Un ejercicio de práctica derivado del repositorio problem-specifications debe tener un fichero .docs/instructions.md (y posiblemente también un fichero .docs/introduction.md) que contenga la documentación del ejercicio procedente de problem-specifications.

Para comprobar en todos los ejercicios de práctica del track si hay actualizaciones de documentación disponibles (saliendo con un código de salida distinto de cero si hay al menos una actualización disponible):

configlet sync --docs

Para actualizar de forma interactiva la documentación de todos los ejercicios de práctica, añade la opción --update (o -u para abreviar):

configlet sync --docs --update

Para actualizar de forma no interactiva la documentación de todos los ejercicios de práctica, añade la opción --yes (o -y para abreviar):

configlet sync --docs --update --yes

Para actuar sobre un solo ejercicio de práctica, usa la opción --exercise (o -e para abreviar). Por ejemplo, para actualizar de forma no interactiva la documentación del ejercicio prime-factors:

configlet sync --docs -uy -e prime-factors

Metadatos

Cada ejercicio de un track debe tener un fichero .meta/config.json. En el caso de un ejercicio de práctica derivado del repositorio problem-specifications, este fichero debe contener los pares clave/valor blurb, source y source_url que existan en el fichero metadata.toml correspondiente en el origen.

Para comprobar en todos los ejercicios de práctica si hay actualizaciones de metadatos disponibles (saliendo con un código de salida distinto de cero si hay al menos una actualización disponible):

configlet sync --metadata

Para actualizar de forma interactiva los metadatos de todos los ejercicios de práctica, añade la opción --update (o -u para abreviar):

configlet sync --metadata --update

Para actualizar de forma no interactiva los metadatos de todos los ejercicios de práctica, añade la opción --yes (o -y para abreviar):

configlet sync --metadata --update --yes

Para actuar sobre un solo ejercicio de práctica, usa la opción --exercise (o -e para abreviar). Por ejemplo, para actualizar de forma no interactiva los metadatos del ejercicio prime-factors:

configlet sync --metadata -uy -e prime-factors

Tests

Si un track implementa un ejercicio para el que existen datos de tests en el repositorio problem-specifications, el ejercicio debe contener un fichero .meta/tests.toml. El objetivo del fichero tests.toml es llevar un registro de qué tests implementa el ejercicio. Los tests de este fichero se identifican por su UUID y cada test tiene un valor booleano que indica si ese ejercicio lo implementa.

Un fichero tests.toml tiene este formato:

# This is an auto-generated file.
#
# Regenerating this file via `configlet sync` will:
# - Recreate every `description` key/value pair
# - Recreate every `reimplements` key/value pair, where they exist in problem-specifications
# - Remove any `include = true` key/value pair (an omitted `include` key implies inclusion)
# - Preserve any other key/value pair
#
# As user-added comments (using the # character) will be removed when this file
# is regenerated, comments can be added via a `comment` key.
[1e22cceb-c5e4-4562-9afe-aef07ad1eaf4]
description = "basic"
[79ae3889-a5c0-4b01-baf0-232d31180c08]
description = "lowercase words"
[ec7000a7-3931-4a17-890e-33ca2073a548]
description = "invalid input"
include = false
comment = "excluded because we don't want to add error handling to the exercise"

En este caso, el track ha decidido implementar dos de los tres tests disponibles. Si un track usa un generador de tests para generar el conjunto de tests de un ejercicio, debe usar el contenido del fichero tests.toml para determinar qué tests incluir en el conjunto de tests generado.

Para comprobar en el fichero tests.toml de cada ejercicio de práctica si hay actualizaciones de tests disponibles (saliendo con un código de salida distinto de cero si hay al menos un caso de test que aparece en los datos canónicos del ejercicio pero no en el tests.toml):

configlet sync --tests

Para actualizar de forma interactiva el fichero tests.toml de todos los ejercicios de práctica, añade la opción --update:

configlet sync --tests --update

Para cada test que falte, se pide al usuario que elija si incluirlo, excluirlo u omitirlo, y se actualiza el fichero tests.toml correspondiente en consecuencia. Configlet escribe el fichero tests.toml de un ejercicio cuando el usuario ha terminado de tomar decisiones para ese ejercicio. Esto significa que puedes terminar configlet mientras está en una solicitud (por ejemplo, pulsando Ctrl-C en el terminal) y solo perderás las decisiones de sincronización de un ejercicio como máximo.

Para incluir de forma no interactiva todos los casos de test que aún no se han visto, usa --tests include. Por ejemplo, para hacerlo con un ejercicio llamado prime-factors:

configlet sync --tests include -u -e prime-factors

¡Recuerda implementar de verdad estos tests en el track!

Rutas de ficheros

Por último, el comando sync también se encarga de «sincronizar» desde una fuente que no es problem-specifications: el fichero config.json a nivel de track. Cada ejercicio de concepto y cada ejercicio de práctica deben tener un fichero .meta/config.json con un objeto files que especifique las ubicaciones (relativas) de los ficheros que usa el ejercicio. Normalmente, estas rutas de ficheros siguen un patrón sencillo, así que configlet puede rellenar los valores a nivel de ejercicio a partir de los patrones de la clave files del fichero config.json a nivel de track.

Para comprobar que todos los ejercicios de concepto y de práctica del track tienen una clave files completamente rellenada (o al menos una que no se pueda rellenar a partir de la clave files a nivel de track):

configlet sync --filepaths

(Ten en cuenta que configlet lint también dará un error cuando a un ejercicio le falte la clave files o la tenga vacía.)

Para rellenar los valores vacíos o ausentes de la clave files a nivel de ejercicio de todos los ejercicios de concepto y de práctica a partir de los patrones de la clave files a nivel de track:

configlet sync --filepaths --update

Para hacerlo de forma no interactiva y para un solo ejercicio llamado prime-factors:

configlet sync --filepaths -uy -e prime-factors

Usar sync al añadir un ejercicio nuevo a un track

El comando sync es útil al añadir un ejercicio nuevo a un track. Si estás añadiendo un ejercicio de práctica llamado foo que existe en problem-specifications, un flujo de trabajo posible es:

  1. Añade manualmente una entrada al fichero config.json a nivel de track para el ejercicio foo. Esto hace que el ejercicio sea visible para configlet sync.
  2. Ejecuta configlet sync --docs --filepaths --metadata -uy -e foo para crear la documentación del ejercicio y un fichero .meta/config.json inicial con los valores files y blurb rellenados y, quizá, también source y source_url.
  3. Edita el fichero .meta/config.json del ejercicio como quieras. Por ejemplo, añádete al array authors.
  4. Ejecuta configlet sync --tests include -u -e foo para crear un fichero .meta/tests.toml con todos los tests incluidos.
  5. Consulta ese fichero .meta/tests.toml y añade include = false a cualquier caso de test que el ejercicio no vaya a implementar.
  6. Implementa los tests del ejercicio para que coincidan con los incluidos en .meta/tests.toml.
  7. Añade los demás ficheros obligatorios.