generic-how-to-implement-a-concept-exercise.md

How to implement a concept exercise

This document describes the steps required to implement a concept exercise in any v3 track.

Please please please read the docs before starting. Posting PRs without reading these docs will be a lot more frustrating for you during the review cycle, and exhaust Exercism's maintainers' time. So, before diving into the implementation, please read the following documents:

• The features of v3.
• Rationale for v3.
• What are concept exercise and how they are structured?

Please also watch the following video:

• The Anatomy of a Concept Exercise.

As this document is generic, the following placeholders are used:

• <LANG>: the name of the track in kebab-case (e.g. ruby).
• <SLUG>: the slug of the exercise in kebab-case (e.g. calculator-conundrum).
• <NAME>: the name of the exercise (e.g. Calculator Conundrum).
• <UUID>: the exercise's unique UUID.
• <CONCEPT_SLUG>: the slug of one of the exercise's concepts in kebab-case (e.g. anonymous-methods).

Before implementing the exercise, please make sure you have a good understanding of what the exercise should be teaching (and what not). This information can be found in the exercise's GitHub issue.

Any concept exercise in any v3 track requires at least the following files to be created:

languages
└── <LANG>
    ├── concepts
    |   └── <CONCEPT_SLUG>
    |       ├── about.md
    |       └── links.json
    └── exercises
        └── concept
            └── <SLUG>
                ├── .docs
                |   ├── introduction.md
                |   ├── instructions.md
                |   ├── hints.md
                |   └── source.md (required if there are third-party sources)
                └── .meta
                    ├── design.md
                    └── config.json

Note that the concept files should be created for each concept the exercise teaches.

All Markdown files should adhere to the style guide, noting the automatic formatting section. Also check any language-specific style guides, where applicable.

The following files need to be added and updated:

Add .docs/introduction.md file

Purpose: Introduce the concept(s) that the exercise teaches to the student.

For more information, please read this in-depth description, watch this video and check this example file.

Add .docs/instructions.md file

Purpose: Provide instructions for the exercise.

For more information, please read this in-depth description, watch this video and check this example file.

Add .docs/hints.md file

Purpose: Provide hints to a student to help them get themselves unstuck in an exercise.

For more information, please read this in-depth description, watch this video and check this example file.

Add .docs/source.md file (required if there are third-party sources)

Purpose: Describe the third-party source(s) of the exercise.

For more information, please read this in-depth description and check this example file.

Skip this step if there aren't any third-party sources.

Add .meta/design.md file

Purpose: Describe the design of the exercise.

For more information, please read this in-depth description, watch this video and check this example file.

Add .meta/config.json file

Purpose: Contains meta information on the exercise.

For more information, please read this in-depth description, watch this video and check this example file.

Update languages/<TRACK>/config.json

Purpose: Contains meta information on the track. Please read this section for more information.

An entry should be added to the track's config.json file for the new concept exercise:

{
  ...
  "exercises": {
    "concept": [
      ...
      {
        "slug": "<SLUG>",
        "name": "<NAME>",
        "uuid": "<UUID>",
        "concepts": ["<CONCEPT-1>"],
        "prerequisites": ["<PREREQUISITE-1>", "<PREREQUISITE-2>"]
      }
    ]
  }
}

• The slug and name must adhere to these naming rules.
• Concepts (and prerequisites) must adhere to these naming rules.
• The UUID can be randomly generated using the UUID Generator.

For more information, please read this in-depth description and check this example file.

Add concepts/<CONCEPT>/about.md for each taught concept

Purpose: Provide information about the concept(s) for a student to learn from.

For more information, check this example file.

Add concepts/<CONCEPT>/links.json for each taught concept

Purpose: Provide helpful links that provide more reading or information about a concept.

For more information, check this example file.

Update reference document(s) (if the reference document(s) exists)

Purpose: Allow maintainers to find out which tracks have implemented an exercise for a concept.

For many concepts, a reference document exists in the reference/concepts or reference/types directories. If such a document exists for the exercise's concept(s), add the exercise to the corresponding exercise's Implementations section or create a new section for your exercise. When no reference document exists, consider writing one.

See this example file.

Add or update story document

Purpose: Allow maintainers to find out which tracks have implemented an exercise for a story.

Each exercise has a story or theme. The stories people have created so far are documented in the reference/stories directory. If such a document exists for the exercise's story, add the exercise to the corresponding exercise's Implementations section. When no story document exists, consider adding one.

See this example file.

Update analyzer (optional)

Some exercises could benefit from having an exercise-specific analyzer. If so, please check the track's analyzer document for details on how to do this.

Skip this step if you're not sure what to do.

Update representer (optional)

Some exercises could benefit from having an custom representation as generated by the track's representer. If so, please check the track's representer document for details on how to do this.

Skip this step if you're not sure what to do.

Inspiration

When implementing an exercise, it can be very useful to look at the exercises the track has already implemented. You can also check the exercise's general concepts documents to see if other languages that have already an exercise for that concept.

Help

If you have any questions regarding implementing this exercise, please post them as comments in the exercise's GitHub issue.