You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+40-17Lines changed: 40 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -50,9 +50,11 @@ Global options:
50
50
51
51
## `configlet lint`
52
52
53
-
The primary function of configlet is to do _linting_: checking if a track's configuration files are properly structured - both syntactically and semantically. Misconfigured tracks may not sync correctly, may look wrong on the website, or may present a suboptimal user experience, so configlet's guards play an important part in maintaining the integrity of Exercism.
53
+
The primary function of configlet is to do _linting_: checking if a track's configuration files are properly structured - both syntactically and semantically.
54
+
Misconfigured tracks may not sync correctly, may look wrong on the website, or may present a suboptimal user experience, so configlet's guards play an important part in maintaining the integrity of Exercism.
54
55
55
-
The `configlet lint` command is still under development. The list of currently implemented checks can be found [here](https://github.com/exercism/configlet/issues/249).
56
+
The `configlet lint` command is still under development.
57
+
The list of currently implemented checks can be found [here](https://github.com/exercism/configlet/issues/249).
56
58
57
59
## `configlet sync`
58
60
@@ -66,15 +68,21 @@ There is also one kind of data that can be populated from the track-level `confi
66
68
67
69
We describe the checking and updating of these data kinds in individual sections below, but as a quick summary:
68
70
69
-
-`configlet sync` only operates on exercises that exist in the track-level `config.json` file. Therefore if you are implementing a new exercise on a track and want to add the initial files with `configlet sync`, please add the exercise to the track-level `config.json` file first. If the exercise is not yet ready to be user-facing, please set its `status` value to `wip`.
71
+
-`configlet sync` only operates on exercises that exist in the track-level `config.json` file.
72
+
Therefore if you are implementing a new exercise on a track and want to add the initial files with `configlet sync`, please add the exercise to the track-level `config.json` file first.
73
+
If the exercise is not yet ready to be user-facing, please set its `status` value to `wip`.
70
74
- A plain `configlet sync` makes no changes to the track, and checks every data kind for every exercise.
71
75
- To operate on a subset of data kinds, use some combination of the `--docs`, `--filepaths`, `--metadata`, and `--tests` options.
72
76
- To interactively update data on the track, use the `--update` option.
73
77
- To non-interactively update docs, filepaths, and metadata on the track, use `--update --yes`.
74
78
- To non-interactively include every unseen test for a given exercise, use e.g. `--update --tests include --exercise prime-factors`.
75
79
- To skip downloading the `problem-specifications` repo, add `--offline --prob-specs-dir /path/to/local/problem-specifications`
76
-
- Note that `configlet sync` tries to maintain the key order in exercise `.meta/config.json` files when updating. To write these files in a canonical form without syncing, please use the `configlet fmt` command. However, `configlet sync`_does_ add (possibly empty) required keys (`authors`, `files`, `blurb`) when they are missing. This is less "sync-like", but more ergonomic: when implementing a new exercise, you can use `sync` to create a starter `.meta/config.json` file.
77
-
-`configlet sync` removes keys that are not in the spec. Custom key/value pairs are still supported: they must be written inside a JSON object named `custom`.
80
+
- Note that `configlet sync` tries to maintain the key order in exercise `.meta/config.json` files when updating.
81
+
To write these files in a canonical form without syncing, please use the `configlet fmt` command.
82
+
However, `configlet sync`_does_ add (possibly empty) required keys (`authors`, `files`, `blurb`) when they are missing.
83
+
This is less "sync-like", but more ergonomic: when implementing a new exercise, you can use `sync` to create a starter `.meta/config.json` file.
84
+
-`configlet sync` removes keys that are not in the spec.
85
+
Custom key/value pairs are still supported: they must be written inside a JSON object named `custom`.
78
86
- The exit code is 0 when all the seen data are synced when configlet exits, and 1 otherwise.
79
87
80
88
Note that in `configlet` releases `4.0.0-alpha.34` and earlier, the `sync` command operated only on tests.
If a track implements an exercise for which test data exists in the [problem-specifications repo](https://github.com/exercism/problem-specifications), the exercise _must_ contain a `.meta/tests.toml` file. The goal of the `tests.toml` 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.
151
+
If a track implements an exercise for which test data exists in the [problem-specifications repo](https://github.com/exercism/problem-specifications), the exercise _must_ contain a `.meta/tests.toml` file.
152
+
The goal of the `tests.toml` file is to keep track of which tests are implemented by the exercise.
153
+
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.
144
154
145
155
A `tests.toml` file has this format:
146
156
@@ -168,7 +178,8 @@ include = false
168
178
comment = "excluded because we don't want to add error handling to the exercise"
169
179
```
170
180
171
-
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.
181
+
In this case, the track has chosen to implement two of the three available tests.
182
+
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.
172
183
173
184
To check every Practice Exercise `tests.toml` file for available tests updates (exiting with a non-zero exit code if there is at least one test case that appears in the exercise's canonical data, but not in the `tests.toml`):
174
185
@@ -186,7 +197,8 @@ For each missing test, this prompts the user to choose whether to include/exclud
186
197
Configlet writes an exercise's `tests.toml` file when the user has finished making choices for that exercise.
187
198
This means that you can terminate configlet at a prompt (for example, by pressing Ctrl-C in the terminal) and only lose the syncing decisions for at most one exercise.
188
199
189
-
To non-interactively include every unseen test case, use `--tests include`. For example, to do so for an exercise named `prime-factors`:
200
+
To non-interactively include every unseen test case, use `--tests include`.
201
+
For example, to do so for an exercise named `prime-factors`:
190
202
191
203
```shell
192
204
configlet sync --tests include -u -e prime-factors
### Using `sync` when adding a new exercise to a track
224
236
225
-
The `sync` command is useful when adding a new exercise to a track. If you are adding a Practice Exercise named `foo` that exists in `problem-specifications`, one possible workflow is:
237
+
The `sync` command is useful when adding a new exercise to a track.
238
+
If you are adding a Practice Exercise named `foo` that exists in `problem-specifications`, one possible workflow is:
226
239
227
-
1. Manually add an entry to the track-level `config.json` file for the exercise `foo`. This makes the exercise visible to `configlet sync`.
240
+
1. Manually add an entry to the track-level `config.json` file for the exercise `foo`.
241
+
This makes the exercise visible to `configlet sync`.
228
242
1. Run `configlet sync --docs --filepaths --metadata -uy -e foo` to create the exercise's documentation, and a starter `.meta/config.json` file with populated `files`, `blurb`, and perhaps `source` and `source_url` values.
229
-
1. Edit the exercise `.meta/config.json` file as desired. For example, add yourself to the `authors` array.
243
+
1. Edit the exercise `.meta/config.json` file as desired.
244
+
For example, add yourself to the `authors` array.
230
245
1. Run `configlet sync --tests include -u -e foo` to create a `.meta/tests.toml` file with every test included.
231
246
1. View that `.meta/tests.toml` file, and add `include = false` to any test case that the exercise will not implement.
232
247
1. Implement the tests for the exercise to match those included in `.meta/tests.toml`.
@@ -325,13 +340,15 @@ The exit code is 0 when every seen exercise has a formatted `.meta/config.json`
325
340
326
341
## `configlet uuid`
327
342
328
-
Each exercise and concept has a [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier), which must only appear once across all of Exercism. It must be a valid version 4 UUID (compliant with RFC 4122) in the canonical textual representation, which means that it must match the below regular expression:
343
+
Each exercise and concept has a [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier), which must only appear once across all of Exercism.
344
+
It must be a valid version 4 UUID (compliant with RFC 4122) in the canonical textual representation, which means that it must match the below regular expression:
Each concept exercise and concept have an `introduction.md` file. If you want the exercise's introduction to include the concept's introduction verbatim, you can create a `introduction.md.tpl` file to achieve this. This file may use a placeholder to refer to the concept's introduction, so that the information is not duplicated.
364
+
Each concept exercise and concept have an `introduction.md` file.
365
+
If you want the exercise's introduction to include the concept's introduction verbatim, you can create a `introduction.md.tpl` file to achieve this.
366
+
This file may use a placeholder to refer to the concept's introduction, so that the information is not duplicated.
348
367
349
368
Concept placeholders must use the following format:
350
369
@@ -358,13 +377,17 @@ For example, if the track has a concept named `floating-point-numbers` then an `
358
377
%{concept:floating-point-numbers}
359
378
```
360
379
361
-
You can run `configlet generate` to generate the exercise's `introduction.md` for any exercise that has an `introduction.md.tpl` file. The generated `introduction.md` is identical to the `introduction.md.tpl`, except that concept placeholders are replaced with the contents of the concept's `introduction.md` file (minus its top-level heading). In the future, `configlet generate` will also increment the level of other headings by 1 (e.g. from `## My Heading` to `### My Heading`), but this is not yet implemented.
380
+
You can run `configlet generate` to generate the exercise's `introduction.md` for any exercise that has an `introduction.md.tpl` file.
381
+
The generated `introduction.md` is identical to the `introduction.md.tpl`, except that concept placeholders are replaced with the contents of the concept's `introduction.md` file (minus its top-level heading).
382
+
In the future, `configlet generate` will also increment the level of other headings by 1 (e.g. from `## My Heading` to `### My Heading`), but this is not yet implemented.
362
383
363
384
## Use in your track
364
385
365
-
Each track should have a `bin/fetch-configlet` script, and might have a `bin/fetch-configlet.ps1` script too. The first is a bash script, and the second is a PowerShell script.
386
+
Each track should have a `bin/fetch-configlet` script, and might have a `bin/fetch-configlet.ps1` script too.
387
+
The first is a bash script, and the second is a PowerShell script.
366
388
367
-
Running one of these scripts downloads the latest version of configlet to the `bin` directory. You can then use configlet by running `bin/configlet` or `bin/configlet.exe` respectively.
389
+
Running one of these scripts downloads the latest version of configlet to the `bin` directory.
390
+
You can then use configlet by running `bin/configlet` or `bin/configlet.exe` respectively.
0 commit comments