Skip to content

Latest commit

 

History

History
136 lines (105 loc) · 6.42 KB

implementing-a-concept-exercise.md

File metadata and controls

136 lines (105 loc) · 6.42 KB

How to implement a JavaScript Concept Exercise

This document describes how to implement a Concept Exercise for the JavaScript 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:

Please also watch the following video:

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

  • <slug>: the simplified name of the exercise in snake_case (e.g. lasagna).
  • <concepts>: the Concepts the exercise is about (e.g. loops),
  • <concept-1>: a single Concept slug,
  • <prerequisite-n>: a single Concept slug,
  • <uuid>: a new v4 UUID (random!)
  • <first-and-last-name>: your first and last name (e.g. Derk-Jan Karrenbeld)
  • <git-email>: the email address you use for git (e.g. [email protected])

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. Having done this, please read the JavaScript Concept exercises introduction. If you have come up with something completely new, create a new issue first so we can discuss the Concept Exercise.

To implement a Concept Exercise, the following files must be added:

github/exercism
└── javascript
    ├── concepts
    |   └── <concept-1>
    |       ├── about.md
    |       ├── introduction.md
    |       └── links.json
    └── exercises
        └── concept
            └── <slug>
                ├── .docs
                |   ├── instructions.md
                |   ├── introduction.md
                |   ├── hints.md
                |   └── source.md (required only if there are third-party sources)
                ├── .meta
                |   |── config.json
                |   |── design.md
                |   └── exemplar.js
                ├── .gitignore
                ├── babel.config.js
                ├── eslint.config.mjs
                ├── global.d.ts (only if there are complex types required)
                ├── jest.config.js
                ├── <slug>.js
                ├── <slug>.spec.js
                ├── package.json
                └── pnpm-lock.yaml

Step 1: Add code files

The configuration files may be copied from another exercise. We aim to keep these in sync:

Warning

Just like with practice exercises, we will provide a script for you to run. This script needs to be updated from its v2 version, which has not yet been done.

  • .gitignore
  • babel.config.js
  • eslint.config.mjs
  • jest.config.js
  • package.json
  • pnpm-lock.yaml

The package.json file must be edited:

-  "name": "@exercism/javascript-lasagna",
+  "name": "@exercism/javascript-<slug>",
-  "description": "Exercism Concept Exercise on <concepts>",
-  "author": "Derk-Jan Karrenbeld <[email protected]>",
+  "author": "<first-and-last-name> <<git-email>>"
   "version": "1.0.0",
   "license": "MIT",
   "private": true,
   "repository": {
     "type": "git",
     "url": "https://github.com/exercism/language-concepts.git",
-    "directory": "languages/javascript/exercises/concept/lasagna"
+    "directory": "languages/javascript/exercises/concept/<slug>"
   },

Now create the following three files:

  • <slug>.js. the stub implementation file, which is the starting point for students to work on the exercise.
  • <slug>.spec.js: the test suite.
  • .meta/exemplar.js: an exemplar implementation that passes all the tests. It should be an idiomatic solution.

Step 2: Add documentation files

How to create the files common to all tracks is described in the how to implement a concept exercise document.

Step 3: Add analyzer (optional)

Some exercises could benefit from having an exercise-specific analyzer. If so, specify what analysis rules should be applied to this exercise and why.

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

Step 4: Add representation (optional)

Some exercises could benefit from having an custom representation as generated by the JavaScript representer. If so, specify what changes to the representation should be applied and why.

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

Inspiration

When implementing an exercise, it can be very useful to look at already implemented JavaScript exercises like the strings, numbers or promises exercises. You can also check the exercise's general concepts documents to see if other languages have already implemented an exercise for that Concept.

Help

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