From d17f02ef927c39cb71b3e0a9f0e9c749653ea21f Mon Sep 17 00:00:00 2001 From: junedev <12543047+junedev@users.noreply.github.com> Date: Sat, 5 Feb 2022 17:43:12 +0100 Subject: [PATCH 1/3] update configlet part in readme --- README.md | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index a9f7b63930..bd67d6e29b 100644 --- a/README.md +++ b/README.md @@ -195,7 +195,12 @@ This is an example of what a re-implementation looks like: ] ``` -## Track Test Data +## Track Data + +Exercism deliberately requires that every exercise has its own copy of certain files (like `.docs/instructions.md`). +There is a tool called [configlet](https://github.com/exercism/configlet), which can check that Practice Exercises on a track are in sync with the problem-specification source, and can update them when updates are available. + +### Track Test Data If a track implements an exercise for which test data exists, the exercise _must_ contain a `.meta/tests.toml` file. The goal of this file is to keep track of which tests are implemented by the exercise. Tests in this file are identified by their UUID and each test has a boolean value that indicates if it is implemented by that exercise. @@ -218,27 +223,36 @@ In this case, the track has chosen to implement two of the three available tests If a track uses a _test generator_ to generate an exercise's test suite, it _must_ use the contents of the `tests.toml` file to determine which tests to include in the generated test suite. -### Track Test Data Tooling +### Track Data Tooling + +To make it easy to keep the data in the track exercises up to date, the [`configlet` application](https://github.com/exercism/configlet)'s provides a `sync` command. +There are three kinds of data that can be updated from `problem-specifications`: documentation, metadata, and tests. -To make it easy to keep the `tests.toml` up to date, tracks should use the [`configlet` application](https://github.com/exercism/configlet)'s `sync` command. -A plain `configlet sync` performs no changes, and just compares the tests specified in the `tests.toml` files against the tests that are defined in the exercise's canonical data - if there are tests defined only in the latter, it prints a summary and exits with a non-zero exit code. +A plain `configlet sync` makes no changes to the track, and checks every data kind for every exercise. +For example, it compares the tests specified in the `tests.toml` files against the tests that are defined in the exercise's canonical data - if there are tests defined only in the latter, it prints a summary and exits with a non-zero exit code. -To interactively update the `tests.toml` files, use `configlet sync --update`. -For each missing test, this prompts the user to choose whether to include/exclude/skip it, and updates the corresponding `tests.toml` file accordingly. +To interactively update the `instructions.md`, `tests.toml` and metadata files, use `configlet sync --update`. + +For documentation and metadata, this prompts the user whether to sync the data with the latest version in problem-specifications. +For each missing test, there is a prompt to choose whether to include/exclude/skip it. +Configlet then updates the corresponding `tests.toml` file accordingly. To non-interactively include every missing test for an exercise `foo`, use: ```console -configlet sync --exercise foo --update --mode include +configlet sync --tests include --exercise foo --update ``` -or the short form `configlet sync -e foo -u -mi`. +or the short form `configlet sync --tests include -e foo -u`. + +Refer to the [documentation for configlet sync](https://exercism.org/docs/building/configlet/sync) for more details on the various command options. The `sync` command operates on Practice Exercises that are in the track-level `config.json` file. If you are adding an exercise that has canonical data to a track, first add that exercise to the track-level `config.json`, and then run a `configlet sync` command to create the corresponding `tests.toml` file. To download the latest version of the `configlet` tool, please run the [`fetch-configlet`](https://github.com/exercism/configlet/blob/main/scripts/fetch-configlet) bash script or the [`fetch-configlet.ps1`](https://github.com/exercism/configlet/blob/main/scripts/fetch-configlet.ps1) PowerShell script (Windows only). At least one of these scripts should already exist in every track repo's `bin` directory - the script will also download `configlet` to this location. You can then sync the tests by running `./bin/configlet sync` (on macOS/Linux/similar) or `.\bin\configlet.exe sync` (on Windows). + ## Conventions There are also some conventions that must be followed: From dc2436324f3c62986a86a02ced645e8afe85f96d Mon Sep 17 00:00:00 2001 From: junedev <12543047+junedev@users.noreply.github.com> Date: Sat, 5 Feb 2022 18:20:43 +0100 Subject: [PATCH 2/3] fix linter error --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index bd67d6e29b..650a5c6e72 100644 --- a/README.md +++ b/README.md @@ -252,7 +252,6 @@ If you are adding an exercise that has canonical data to a track, first add that To download the latest version of the `configlet` tool, please run the [`fetch-configlet`](https://github.com/exercism/configlet/blob/main/scripts/fetch-configlet) bash script or the [`fetch-configlet.ps1`](https://github.com/exercism/configlet/blob/main/scripts/fetch-configlet.ps1) PowerShell script (Windows only). At least one of these scripts should already exist in every track repo's `bin` directory - the script will also download `configlet` to this location. You can then sync the tests by running `./bin/configlet sync` (on macOS/Linux/similar) or `.\bin\configlet.exe sync` (on Windows). - ## Conventions There are also some conventions that must be followed: From 15a847ec4ecfbce8acfc1b116d55e840613b72da Mon Sep 17 00:00:00 2001 From: June <12543047+junedev@users.noreply.github.com> Date: Wed, 9 Feb 2022 14:43:31 +0100 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: ee7 <45465154+ee7@users.noreply.github.com> --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 650a5c6e72..184e8496dc 100644 --- a/README.md +++ b/README.md @@ -198,7 +198,7 @@ This is an example of what a re-implementation looks like: ## Track Data Exercism deliberately requires that every exercise has its own copy of certain files (like `.docs/instructions.md`). -There is a tool called [configlet](https://github.com/exercism/configlet), which can check that Practice Exercises on a track are in sync with the problem-specification source, and can update them when updates are available. +There is a tool called [configlet](https://github.com/exercism/configlet), which can check that Practice Exercises on a track are in sync with the `problem-specifications` source, and can update them when updates are available. ### Track Test Data @@ -225,7 +225,7 @@ If a track uses a _test generator_ to generate an exercise's test suite, it _mus ### Track Data Tooling -To make it easy to keep the data in the track exercises up to date, the [`configlet` application](https://github.com/exercism/configlet)'s provides a `sync` command. +To make it easy to keep the data in the track exercises up to date, the [`configlet` application](https://github.com/exercism/configlet) provides a `sync` command. There are three kinds of data that can be updated from `problem-specifications`: documentation, metadata, and tests. A plain `configlet sync` makes no changes to the track, and checks every data kind for every exercise.