The first exercise on each track is a very simple "Hello, World!" exercise.
The point of this exercise is to quickly make sure that everything is wired together correctly. This will confirm that the user has the programming environment installed correctly, that they know how to run the tests, and are able to make it pass. Beyond this, for Exercism command-line client (CLI) it also ensures that they have the CLI installed and configured properly, and that the site delivers the correct files for the exercise without delivering any unnecessary artifacts. Lastly it ensures that the user is familiar with the cycle of downloading an exercise using the CLI, solving a problem in their local development environment, and submitting their solution back to the site.
In other words, this is not really about learning anything about the language itself yet. We are aiming for something dead simple.
This is also probably going to be the hardest part of getting the track repository set up right, as there are a lot of moving parts to implementing an exercise.
The "Hello, World!" exercise has some special rules applied to it:
prerequisites
practices
The "Hello, World!" exercise (and indeed, all exercises on Exercism) requires a specific set of files:
Before we can create the "Hello, World!" exercise, you need to make some decisions about the track-specific filenames and file paths (test suite, stub implementation, example implementation and any additional files).
The rule of thumb is to use names that are idiomatic for the language.
Where there are no strong preferences, prefer shallower directory structures.
The example implementation will need to be identifiable by the CI script, so it's advisable to choose a generic basename that all exercises can use, e.g. example
, sample
, or reference-solution
.
Having chosen the track-specific file paths, you should configure them in the files
key in the root config.json
file.
The files
key will serve as the template for all exercises, which allows any tooling (some of which we'll use in a second) to know where to look for files.
You can use various placeholders to allow for easy configuring of the exercise's slug (hello-world
in this case).
If your track uses PascalCase for its files, the files
key might look like this:
"files": {
"solution": [
"%{pascal_slug}.cs"
],
"test": [
"%{pascal_slug}Tests.cs"
],
"example": [
".meta/Example.cs"
]
}
The example file(s) should be stored within the .meta
directory.
For more information, check the files
key documentation.
Having specified the file path templates, you can then quickly scaffold the "Hello, World!" exercise's files by running the following commands from the track's root directory:
bin/fetch-configlet
bin/configlet create --practice-exercise hello-world
To have the website list you as the exercise's author, follow these steps:
Within the exercise's .meta/config.json
file:
authors
keyFor this to work, you'll need link your Exercism account to GitHub. You can do this on the website in the Settings page's Integrations section.
Exercise authors are also awarded reputation
Newer track repos can use the bin/add-practice-exercise
script (source) to add new exercises:
bin/add-exercise -a <github_username> two-fer
If you're working on a track repo without this file, feel free to copy them into your repo using the above source link.
Once the scaffolded files have been created, you'll then have to:
A key part of adding an exercise is adding tests. Rougly speaking, there are two options when implementing one of the above exercises:
canonical-data.json
https://exercism.org/exercises/hello-world
to get an overview of which tracks have implemented a specific exercise).For the "Hello, World!" exercise, there will only be one test case, so either option should be fine.
The example implementation file should contain the code requires to solve the tests.
The stub file should have an almost working solution to the tests, but with the "Hello, World!" text replaced with "Goodbye, Mars!". Tip: just can copy-paste-modify the example solution.
Once you're done with the exercise, please add your your GitHub username to the "authors"
array in the exercise's .meta/config.json
file.
This will ensure we correctly credit you with having created the exercise.
To verify that the exercise is setup correctly, you can use the configlet tool's built-in linting functionality.
The first step is to fetch the configlet
tool, for which we've created two scripts:
bin/fetch-configlet
: run this when using *nix or macOSbin/fetch-configlet.ps1
: run this when using WindowsRunning one of these scripts from the root directory of the track's repo will download the bin/configlet
respectively bin/configlet.exe
binary.
You can then check the exercise for correctness by running bin/configlet lint
.
It is likely that configlet
will report the following error:
The `tags` array is empty:
/path/to/track/config.json
This error will be fixed in the Prepare for launch step, so either:
The configlet
workflow will automatically runs configlet lint
whenever something is pushed to main
or to a pull request.