contributing-to-practice-exercises.md

Contributing to Practice Exercises

There are two types of practice exercises in the Java track.

• The most common are come from the problem specifications repository. The repository contains data that is common for all implementations, such as the introduction, instructions and the test cases.

• The others do not have data in the problem specification and are specific to the Java track.

If you are looking to add a completely new exercise that is not from the problem specifications repository, please open a discussion in the forums in the Java category for Java specific exercises or the Building Exercism category for adding to the problem specifications repository.

If the exercise is already in the problem specifications, please check that no one else has claimed the issue or pull request. An issue can be "claimed" by asking (in a comment on the issue) if you can work on it.

Adding a new Practice Exercise

Before adding an exercise to the Java track, please review the practice exercise guide.

The easiest way to get started is to use configlet to provide some of the scaffolding.

configlet create --practice-exercise <exercise-slug>

This will create the necessary entries in config.json, create the directory and pulls the exercise's document files from the problem specifications repository.

The Java specific details you need to know about adding an exercise are:

• Please check the entry added by configlet to the exercises array in config.json. The entries are sorted by difficulty, then name. You can find details about what should be in that entry at the Exercism docs. You can also look at other entries in config.json as examples and try to mimic them.

• Please add an entry for your exercise to settings.gradle. This should just be include 'concept:exercise-name' for concept exercises, or include 'practice:exercise-name' for practice exercises. This list is in alphabetical order so please add your exercise so that it maintains this order.

• Please add an exercise submodule for your exercise. In the resources/exercise-template you will find a template to get you started. See The Problem Submodules section for details on how each exercise submodule is structured.

• Please copy and add the Gradle files and directories from the resources/exercise-template directory. This should allow you to run Gradle from the exercise's directory.

• Make sure you've followed the track policies, especially the ones for exercise added/updated.

Hopefully that should be enough information to help you add a practice exercise to the Java track. Feel free to open an issue or post in the Building Exercism category of the Exercism forum if you have any questions, and we'll try and answer as soon as we can.

Updating the documentation for an exercise

The documentation files for practice exercises are generated from the exercise descriptions in problem specifications. In case one of these exercise descriptions change, these documentation files can be regenerated by running the configlet from the root of this repository:

bin/configlet sync --docs --metadata --update --exercise <exercise-slug>

Updating the tests for an exercise

For exercises from the problem specification, the tests are based on the canonical data. The practice exercise should contain a .meta/tests.toml file containing the test cases that were implemented for that exercise.

In case the canonical data for an exercise changes, this file can be updated by running the configlet from the root of this repository:

bin/configlet sync --tests --update --exercise <exercise-slug>

Note that this only updates the .meta/tests.toml file. Any tests that were added or updated should be implemented in the exercise's unit tests!

Syncing is not required for Java specific exercises.