From 1c8ba89221a495b0c36cf37e36b233bd158cce1d Mon Sep 17 00:00:00 2001 From: Erik Schierboom Date: Tue, 15 Nov 2022 16:43:35 +0100 Subject: [PATCH 1/2] Document snippet extension --- building/configlet/lint.md | 3 ++- building/tracks/approaches.md | 4 ++++ building/tracks/config-json.md | 5 +++++ 3 files changed, 11 insertions(+), 1 deletion(-) diff --git a/building/configlet/lint.md b/building/configlet/lint.md index 5d001e85..e658c1b1 100644 --- a/building/configlet/lint.md +++ b/building/configlet/lint.md @@ -375,10 +375,11 @@ The `config.json` file should have the following checks: - The Markdown must conform to the [Markdown standards](/docs/building/markdown/markdown) - Links must be absolute (relative links are not allowed) -### Rule: exercises/{concept|practice}/<slug>/.approaches/<approach-slug>/snippet.txt is valid +### Rule: exercises/{concept|practice}/<slug>/.approaches/<approach-slug>/snippet.<snippet-extension> is valid - The file's presence is required if a matching `"approaches[].slug"` entry exists in the `.approaches/config.json` file - The snippet must have at most 8 lines +- The snippet extension is taken from the `approaches.snippet_extension` value in the track's `config.json` file ### Rule: exercises/{concept|practice}/<slug>/.articles/config.json is valid diff --git a/building/tracks/approaches.md b/building/tracks/approaches.md index 1a2a70be..13496568 100644 --- a/building/tracks/approaches.md +++ b/building/tracks/approaches.md @@ -42,3 +42,7 @@ If you'd like to compare different approaches, please write an [articles](/docs/ In general, [Practice Exercises](/docs/building/tracks/practice-exercises) are more suitable to write approaches for, as they usually can be solved in multiple ways. For [Concept Exercises](/docs/building/tracks/concept-exercises), discussing the exemplar approach might be interesting. For example, you could show how the concept being taught makes certain code easier to write. + +## Configuring + +Make sure to set the `approaches.snippet_extension` field in your [track's `config.json` file](/docs/building/tracks/config-json). diff --git a/building/tracks/config-json.md b/building/tracks/config-json.md index 865d4739..6d62b666 100644 --- a/building/tracks/config-json.md +++ b/building/tracks/config-json.md @@ -28,6 +28,8 @@ The following top-level properties contain general track metadata: - `editor`: additional read-only editor file(s) patterns (optional) - `test_runner`: an object describing the track's test runner (if any): (required if `status.test_runner` is `true`) - `average_run_time`: a `number` value for the number of seconds the test runner takes on average to run, rounded to one decimal point precision (e.g. `1.8`) (required if `status.test_runner` is `true`) +- `approaches`: an object with metadata on the track's approaches: (required if the track has any approaches) + - `snippet_extension`: a string value used for the snippet file's extension (e.g. `rb`) (required if the track has any approaches) ### Files @@ -70,6 +72,9 @@ Support will be added to [configlet](/docs/building/configlet) to use these patt }, "test_runner": { "average_run_time": 2.3 + }, + "approaches": { + "snippet_extension": "cs" } } ``` From 4f54e615d180cfe45654f7d4d2a8a1d86bbb7279 Mon Sep 17 00:00:00 2001 From: Erik Schierboom Date: Wed, 16 Nov 2022 08:27:56 +0100 Subject: [PATCH 2/2] Add linting rule --- building/configlet/lint.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/building/configlet/lint.md b/building/configlet/lint.md index e658c1b1..0cd3cb68 100644 --- a/building/configlet/lint.md +++ b/building/configlet/lint.md @@ -109,6 +109,8 @@ The `config.json` file should have the following checks: - The `"files.example` and `"files.exemplar"` files _can_ overlap - The `"test_runner.average_run_time"` key is required if `"status.test_runner"` is equal to `true` - The `"test_runner.average_run_time"` value must be a floating-point number > 0 with one decimal point of precision +- The `"approaches.snippet_extension"` key is required if the track has one or more approaches +- The `"approaches.snippet_extension"` value must be a non-blank string¹ - The `"exercises"` key is required - The `"exercises.concept"` key is required - The `"exercises.concept"` value must be an array