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). diff --git a/building/tracks/concept-exercises.md b/building/tracks/concept-exercises.md index 337b2863..d551807a 100644 --- a/building/tracks/concept-exercises.md +++ b/building/tracks/concept-exercises.md @@ -4,6 +4,17 @@ The concepts taught by the concept exercises form a _syllabus_. For more information on how to design a syllabus, check the [syllabus documentation](/docs/building/tracks/syllabus). +````exercism/note +You can quickly scaffold a new Concept Exercise by running the following commands from the track's root directory: + +```shell +bin/fetch-configlet +bin/configlet create --concept-exercise +``` + +For more information, check the [`configlet create` docs](/docs/building/configlet/create) +```` + ## Metadata Concept Exercise metadata is defined in the `exercises.concept` key in the [config.json file](/docs/building/tracks/config-json#concept-exercises). The metadata defines the exercise's UUID, slug and more. diff --git a/building/tracks/practice-exercises.md b/building/tracks/practice-exercises.md index 51fb7bfa..e6eccb0d 100644 --- a/building/tracks/practice-exercises.md +++ b/building/tracks/practice-exercises.md @@ -6,6 +6,17 @@ Interested in adding your first Practice Exercise to a track? Watch our walkthro [video:vimeo/906101866?h=2954ad331e]() +````exercism/note +You can quickly scaffold a new Practice Exercise by running the following commands from the track's root directory: + +```shell +bin/fetch-configlet +bin/configlet create --practice-exercise +``` + +For more information, check the [`configlet create` docs](/docs/building/configlet/create) +```` + ## Metadata Practice Exercise metadata is defined in the `exercises.practice` key in the [config.json file](/docs/building/tracks/config-json). The metadata defines the exercise's UUID, slug and more.