From c447a5b063d029ccfc244bf74ec0063f94e5b4ea Mon Sep 17 00:00:00 2001 From: Erik Schierboom Date: Thu, 25 Jan 2024 12:18:05 +0100 Subject: [PATCH] configlet: document `create` command --- building/configlet/README.md | 6 +++ building/configlet/create.md | 95 ++++++++++++++++++++++++++++++++++++ 2 files changed, 101 insertions(+) create mode 100644 building/configlet/create.md diff --git a/building/configlet/README.md b/building/configlet/README.md index 6babe588..03ba944c 100644 --- a/building/configlet/README.md +++ b/building/configlet/README.md @@ -36,6 +36,12 @@ Tests in this file are identified by their UUID and each test has a boolean valu You can find the details about how to sync the different parts of an exercise [here](/docs/building/configlet/sync). +## Create files + +Configlet can be used to quickly scaffold files for a new approach, article or exercise. + +You can learn more about how to create these files [here](/docs/building/configlet/create). + ## Generating UUIDs Exercises, tracks and concepts are identified by a UUID. diff --git a/building/configlet/create.md b/building/configlet/create.md new file mode 100644 index 00000000..3ab9ff5b --- /dev/null +++ b/building/configlet/create.md @@ -0,0 +1,95 @@ +# Configlet creating files + +When adding a new approach, article or exercise, you'll have to create files with very specific names. +They also require configuration files to be added or updated. +With the `create` command, [configlet](/docs/building/configlet) can do all this for you. + +## Usage + +The `create` command can be used to create the files required to add a new approach, article or exercise, as well as modify any configuration files. + +```shell +configlet [global-options] create [command-options] + +Options for create: + --approach The slug of the approach + --article The slug of the article + --practice-exercise The slug of the practice exercise + --concept-exercise The slug of the concept exercise + -e, --exercise Only operate on this exercise + -o, --offline Do not update the cached 'problem-specifications' data +``` + +## Create Practice Exercise + +To create a practice exercise, one has to specify its slug: + +```shell +configlet create --practice-exercise collatz-conjecture +``` + +This will create the practice exercise's required files, as specified in the [Practice Exercises docs](/docs/building/tracks/practice-exercises). +If the practice exercise is defined in the [Problem Specifications repo](https://github.com/exercism/problem-specifications/), configlet will sync the docs and metadata from there. + +Of course, this is just the first step towards creating an exercise. +You'll then have to: + +- Add tests to the tests file +- Add an example implementation +- Define the stub file's contents +- Within the exercise's `.meta/config.json` file: + - Add the GitHub username of the exercise's authors to the `authors` key +- Within the track's `config.json` file: + - Check/update the exercise's difficulty + - Add concepts to the `practices` key (only required when the track has concept exercises) + - Add concepts to the `prerequisites` key (only required when the track has concept exercises) + +```exercism/note +Some tracks have implemented an exercise/test _generator_, which is a tool that can generate the test file's contents based on the exercise's `canonical-data.json` found in the [Problem Specifications repo](https://github.com/exercism/problem-specifications/). +Make sure to read the track's documentation to see if there is a generator that you can use. +``` + +## Create Concept Exercise + +To create a concept exercise, one has to specify its slug: + +```shell +configlet create --concept-exercise bird-watcher +``` + +This will create the concept exercise's required files, as specified in the [Concept Exercises docs](/docs/building/tracks/concept-exercises). + +Of course, this is just the first step towards creating an exercise. +You'll then have to: + +- Add tests to the tests file +- Add an exemplar implementation +- Define the stub file's contents +- Write the introduction in `.docs/introduction.md` +- Write the instructions in `.docs/instructions.md` +- Within the exercise's `.meta/config.json` file: + - Add the GitHub username of the exercise's authors to the `authors` key +- Within the track's `config.json` file: + - Check/update the exercise's difficulty + - Add concepts to the `concepts` key + - Add concepts to the `prerequisites` key + +## Create Approach + +To create an approach's files, one has to specify the slug of the approach and its exercise: + +```shell +configlet create --approach recursion --exercise collatz-conjecture +``` + +This will create the approach's required files, as specified in the [Approaches docs](/docs/building/tracks/approaches). + +## Create Article + +To create an article's files, one has to specify the slug of the article and its exercise: + +```shell +configlet create --article performance --exercise collatz-conjecture +``` + +This will create the article's required files, as specified in the [Articles docs](/docs/building/tracks/articles).