Skip to content

Commit 6033961

Browse files
authored
README: use one line per sentence (#496)
This commit only adds newlines. It doesn't change how the document is rendered, but it makes diffs more obvious. This is one of Exercism's preferences for Markdown - see: https://github.com/exercism/docs/blob/79a253f42bfc/building/markdown/markdown.md#one-sentence-per-line
1 parent 9296b43 commit 6033961

1 file changed

Lines changed: 40 additions & 17 deletions

File tree

README.md

Lines changed: 40 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -50,9 +50,11 @@ Global options:
5050

5151
## `configlet lint`
5252

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.
5455

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).
5658

5759
## `configlet sync`
5860

@@ -66,15 +68,21 @@ There is also one kind of data that can be populated from the track-level `confi
6668

6769
We describe the checking and updating of these data kinds in individual sections below, but as a quick summary:
6870

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`.
7074
- A plain `configlet sync` makes no changes to the track, and checks every data kind for every exercise.
7175
- To operate on a subset of data kinds, use some combination of the `--docs`, `--filepaths`, `--metadata`, and `--tests` options.
7276
- To interactively update data on the track, use the `--update` option.
7377
- To non-interactively update docs, filepaths, and metadata on the track, use `--update --yes`.
7478
- To non-interactively include every unseen test for a given exercise, use e.g. `--update --tests include --exercise prime-factors`.
7579
- 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`.
7886
- The exit code is 0 when all the seen data are synced when configlet exits, and 1 otherwise.
7987

8088
Note that in `configlet` releases `4.0.0-alpha.34` and earlier, the `sync` command operated only on tests.
@@ -140,7 +148,9 @@ configlet sync --metadata -uy -e prime-factors
140148

141149
### Tests
142150

143-
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.
144154

145155
A `tests.toml` file has this format:
146156

@@ -168,7 +178,8 @@ include = false
168178
comment = "excluded because we don't want to add error handling to the exercise"
169179
```
170180

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.
172183

173184
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`):
174185

@@ -186,7 +197,8 @@ For each missing test, this prompts the user to choose whether to include/exclud
186197
Configlet writes an exercise's `tests.toml` file when the user has finished making choices for that exercise.
187198
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.
188199

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`:
190202

191203
```shell
192204
configlet sync --tests include -u -e prime-factors
@@ -222,11 +234,14 @@ configlet sync --filepaths -uy -e prime-factors
222234

223235
### Using `sync` when adding a new exercise to a track
224236

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:
226239

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`.
228242
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.
230245
1. Run `configlet sync --tests include -u -e foo` to create a `.meta/tests.toml` file with every test included.
231246
1. View that `.meta/tests.toml` file, and add `include = false` to any test case that the exercise will not implement.
232247
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`
325340

326341
## `configlet uuid`
327342

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:
329345

330346
```text
331347
^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
332348
```
333349

334-
You can run `configlet uuid` to output a new, appropriate UUID. There is also the `-n, --num` option for outputting multiple new UUIDs:
350+
You can run `configlet uuid` to output a new, appropriate UUID.
351+
There is also the `-n, --num` option for outputting multiple new UUIDs:
335352

336353
```console
337354
$ configlet uuid --num 5
@@ -344,7 +361,9 @@ e42b94bb-9c90-47f2-aebb-03cdbc27bf3b
344361

345362
## `configlet generate`
346363

347-
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.
348367

349368
Concept placeholders must use the following format:
350369

@@ -358,13 +377,17 @@ For example, if the track has a concept named `floating-point-numbers` then an `
358377
%{concept:floating-point-numbers}
359378
```
360379

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.
362383

363384
## Use in your track
364385

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.
366388

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.
368391

369392
## Contributing
370393

0 commit comments

Comments
 (0)