configlet sync

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

Un ejercicio de práctica en una pista de Exercism a menudo se implementa a partir de una especificación en el repositorio exercism/problem-specifications.

Exercism requiere deliberadamente que cada ejercicio tenga su propia copia de ciertos archivos (como .docs/instructions.md), incluso cuando ese ejercicio existe en problem-specifications. Por lo tanto, configlet tiene un comando sync, que puede verificar que dichos ejercicios de práctica en una pista estén sincronizados con esa fuente upstream, y puede actualizarlos cuando hay actualizaciones disponibles.

Hay tres tipos de datos que se pueden actualizar desde problem-specifications: documentación, metadatos y pruebas. También hay un tipo de datos que se pueden rellenar desde el archivo config.json a nivel de pista: las rutas de archivos en los archivos de configuración del ejercicio.

Describimos la verificación y actualización de estos tipos de datos en secciones individuales a continuación, pero como resumen rápido:

  • configlet sync solo opera en ejercicios que existen en el archivo config.json a nivel de pista. Por lo tanto, si estás implementando un nuevo ejercicio en una pista y quieres agregar los archivos iniciales con configlet sync, primero agrega el ejercicio al archivo config.json a nivel de pista. Si el ejercicio aún no está listo para ser visible para los usuarios, establece su valor status en wip.
  • Un configlet sync simple no hace cambios en la pista, y verifica cada tipo de datos para cada ejercicio.
  • Para operar en un subconjunto de tipos de datos, usa alguna combinación de las opciones --docs, --filepaths, --metadata y --tests.
  • Para actualizar datos de forma interactiva en la pista, usa la opción --update.
  • Para actualizar la documentación, las rutas de archivos y los metadatos de forma no interactiva en la pista, usa --update --yes.
  • Para incluir de forma no interactiva cada prueba no vista para un ejercicio dado, usa, por ejemplo, --update --tests include --exercise prime-factors.
  • Para omitir la descarga del repositorio problem-specifications, agrega --offline --prob-specs-dir /path/to/local/problem-specifications
  • Ten en cuenta que configlet sync intenta mantener el orden de las claves en los archivos .meta/config.json del ejercicio al actualizar. Para escribir estos archivos en una forma canónica sin sincronizar, usa el comando configlet fmt. Sin embargo, configlet sync sí agrega claves requeridas (posiblemente vacías) (authors, files, blurb) cuando faltan. Esto es menos "parecido a sync", pero más ergonómico: al implementar un nuevo ejercicio, puedes usar sync para crear un archivo .meta/config.json inicial.
  • configlet sync elimina las claves que no están en la especificación. Los pares clave/valor personalizados aún son 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 cuando configlet finaliza, y 1 en caso contrario.

Ten en cuenta que en las versiones de configlet 4.0.0-alpha.34 y anteriores, el comando sync operaba solo en las pruebas.

Uso

El comando sync se puede usar para verificar o actualizar los documentos, metadatos y pruebas de los ejercicios de práctica desde «problem-specifications». También puede verificar o rellenar valores files faltantes para ejercicios de concepto/práctica desde el «config.json» de la pista.

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 que se deriva del repositorio problem-specifications debe tener un archivo .docs/instructions.md (y posiblemente también un archivo .docs/introduction.md) que contenga la documentación del ejercicio de problem-specifications.

Para verificar cada ejercicio de práctica en la pista en busca de actualizaciones de documentación disponibles (saliendo con un código de salida distinto de cero si al menos una actualización está disponible):

configlet sync --docs

Para actualizar la documentación de cada ejercicio de práctica de forma interactiva, agrega la opción --update (o -u para abreviar):

configlet sync --docs --update

Para actualizar la documentación de cada ejercicio de práctica de forma no interactiva, agrega la opción --yes (o -y para abreviar):

configlet sync --docs --update --yes

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

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

Metadatos

Cada ejercicio en una pista debe tener un archivo .meta/config.json. Para un ejercicio de práctica que se deriva del repositorio problem-specifications, este archivo debe contener los pares clave/valor blurb, source y source_url que existen en el archivo metadata.toml upstream correspondiente.

Para verificar cada ejercicio de práctica en busca de actualizaciones de metadatos disponibles (saliendo con un código de salida distinto de cero si al menos una actualización está disponible):

configlet sync --metadata

Para actualizar los metadatos de cada ejercicio de práctica de forma interactiva, agrega la opción --update (o -u para abreviar):

configlet sync --metadata --update

Para actualizar los metadatos de cada ejercicio de práctica de forma no interactiva, agrega la opción --yes (o -y para abreviar):

configlet sync --metadata --update --yes

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

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

Pruebas

Si una pista implementa un ejercicio para el cual existen datos de prueba en el repositorio problem-specifications, el ejercicio debe contener un archivo .meta/tests.toml. El objetivo del archivo tests.toml es llevar un registro de qué pruebas implementa el ejercicio. Las pruebas en este archivo se identifican por su UUID y cada prueba tiene un valor booleano que indica si está implementada por ese ejercicio.

Un archivo 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, la pista ha elegido implementar dos de las tres pruebas disponibles. Si una pista usa un generador de pruebas para generar el conjunto de pruebas de un ejercicio, debe usar el contenido del archivo tests.toml para determinar qué pruebas incluir en el conjunto de pruebas generado.

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

configlet sync --tests

Para actualizar el archivo tests.toml de cada ejercicio de práctica de forma interactiva, agrega la opción --update:

configlet sync --tests --update

Para cada prueba faltante, esto le pide al usuario que elija si incluirla, excluirla u omitirla, y actualiza el archivo tests.toml correspondiente en consecuencia. Configlet escribe el archivo tests.toml de un ejercicio cuando el usuario ha terminado de tomar decisiones para ese ejercicio. Esto significa que puedes terminar configlet en un aviso (por ejemplo, presionando Ctrl-C en la terminal) y solo perderás las decisiones de sincronización de como máximo un ejercicio.

Para incluir de forma no interactiva cada caso de prueba no visto, usa --tests include. Por ejemplo, para hacerlo con un ejercicio llamado prime-factors:

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

¡Recuerda implementar realmente estas pruebas en la pista!

Rutas de archivos

Finalmente, el comando sync también maneja la «sincronización» desde una fuente que no es problem-specifications: el archivo config.json a nivel de pista. Cada ejercicio de concepto y ejercicio de práctica debe tener un archivo .meta/config.json con un objeto files que especifique las ubicaciones (relativas) de los archivos que usa el ejercicio. Dichas rutas de archivos generalmente siguen un patrón simple, por lo que configlet puede rellenar los valores a nivel de ejercicio a partir de patrones en la clave files del archivo config.json a nivel de pista.

Para verificar que cada ejercicio de concepto y ejercicio de práctica en la pista tenga una clave files completamente poblada (o al menos una que no se pueda poblar desde la clave files a nivel de pista):

configlet sync --filepaths

(Ten en cuenta que configlet lint también producirá un error cuando un ejercicio tenga una clave files faltante o vacía).

Para rellenar valores vacíos o faltantes de la clave files a nivel de ejercicio para cada ejercicio de concepto y ejercicio de práctica a partir de los patrones en la clave files a nivel de pista:

configlet sync --filepaths --update

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

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

Usar sync al agregar un nuevo ejercicio a una pista

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

  1. Agrega manualmente una entrada al archivo config.json a nivel de pista 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 archivo .meta/config.json inicial con valores files, blurb y quizás source y source_url poblados.
  3. Edita el archivo .meta/config.json del ejercicio como desees. Por ejemplo, agrégate al array authors.
  4. Ejecuta configlet sync --tests include -u -e foo para crear un archivo .meta/tests.toml con cada prueba incluida.
  5. Revisa ese archivo .meta/tests.toml y agrega include = false a cualquier caso de prueba que el ejercicio no vaya a implementar.
  6. Implementa las pruebas para el ejercicio para que coincidan con las incluidas en .meta/tests.toml.
  7. Agrega los otros archivos requeridos.