contributing-to-practice-exercises.md

Contributing to Practice Exercises

Adding a new Practice Exercise

The easiest way to add a new exercise to the Java track is to port an exercise from another track. That means that you take an exercise that has already been implemented in another language, and you implement it in this track.

To add a completely new exercise you need to open a pull request to the problem specifications repository. Any completely new exercise needs to be added and accepted there before it can be added to the Java track.

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

Please make sure no one else has a pull request open to implement your chosen exercise before you start.

It might also be a good idea to open a Pull Request to make it clear to others that you are working on this exercise. This can just be a Pull Request with an empty commit that states which new exercise you're working on. Mark the Pull Request as Draft to let the maintainers know that it's not ready for review yet.

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

• Please add an entry to the exercises array in config.json. You can find details about what should be in that entry [here][docs-building-config-json]. 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. See The Problem Submodules section for what needs to be in this. See the Policies for an explanation of when you need to add a starter implementation. The build.gradle file can just be copied from any other exercise submodule.

• Use the configlet to generate documentation and metadata files for the new exercise.

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

Hopefully that should be enough information to help you port an 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

The tests for practice exercises are based on the canonical data in problem specification. Each 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!