Developer docs by TheRealOwenRees · Pull Request #11 · exercism/rescript

TheRealOwenRees · 2026-03-10T10:30:21Z

first draft of updating the repository's readme for contributing to the ReScript language track

BNAndras · 2026-03-11T18:13:30Z

+Now complete the following steps:
+
+- `config.json` - ensure that the new exercise data is correctly placed in order of difficulty and then alphabetically within that difficulty rating.
+- implement exercise test cases, detailed in the [testing](#testing) section below.


We should be clear here that they need to make a template file first for the test generator to run. They then need to run the generator, making sure it runs a compilable ReScriptTest suite. Tests may need to be excluded from the tests.toml as well so that should be done as well. However, test generator may need to be rerun after you start working on the example solution and find a test for make sense for ReScript. Therefore we should mention or link out about the toml and how to skip a test there.

Most of that is in the below section but it should be inlined here or introduced beforehand.

Perhaps we break this into task-related sections:

Generating Tests?

Do this...

Updating An Existing Exercise?

Do this...

Adding A New Exercise?

Do this...

The latest commit is draft 1 of this section. Please review. It is likely rough around the edges. I have commented out the old version for now, for reference.

Can we remove the old version? Generally, it's old for a reason, and it's hard for me to skim through the file since I need to track regularly whether I'm in a commented-out section or not. The old versions if we need them are in the commit history.

yes i will do that this evening, and start working on the suggestions

BNAndras · 2026-06-07T00:47:15Z

I’ll take a look this weekend.

BNAndras · 2026-06-07T01:14:39Z

+
+- **Configure the test template:** Edit `test_templates/<ExerciseName>_template.res`. Delete and uncomment the code where indicated. Use previous templates as examples of how to achieve what you need. Common comparator functions are found in `test_generator/Assertions.res`
+
+- **Generate and run tests:** To build the test file and run it, run `make test EXERCISE=<exercise-slug>`. Your generated test cases are found in `exercises/<exercise-slug>/tests/<ExerciseName>_test.res`. Verify that the test cases accept and return the correct data.


Suggested change

- **Generate and run tests:** To build the test file and run it, run `make test EXERCISE=<exercise-slug>`. Your generated test cases are found in `exercises/<exercise-slug>/tests/<ExerciseName>_test.res`. Verify that the test cases accept and return the correct data.

- **Generate and run tests:** To build the test file and run it, run `make test EXERCISE=<exercise-slug>`. Your generated test cases are found in `exercises/practice/<exercise-slug>/tests/<ExerciseName>_test.res`. Verify that the test cases accept and return the correct data.

BNAndras · 2026-06-07T01:15:32Z

+
+- **Generate and run tests:** To build the test file and run it, run `make test EXERCISE=<exercise-slug>`. Your generated test cases are found in `exercises/<exercise-slug>/tests/<ExerciseName>_test.res`. Verify that the test cases accept and return the correct data.
+
+- **Creating new comparator functions:** If none of the comparator functions satisfy the exercise's test requirements, you can write a new one in `test_generator/Assertions.res` and `test_generator/AssersionGenerators.res`, following the guidelines at https://bloodyowl.github.io/rescript-test/assertions. The function should be returned as a string, so that our templating system can inject the code into the generated tests.


Suggested change

- **Creating new comparator functions:** If none of the comparator functions satisfy the exercise's test requirements, you can write a new one in `test_generator/Assertions.res` and `test_generator/AssersionGenerators.res`, following the guidelines at https://bloodyowl.github.io/rescript-test/assertions. The function should be returned as a string, so that our templating system can inject the code into the generated tests.

- **Creating new comparator functions:** If none of the comparator functions satisfy the exercise's test requirements, you can write a new one in `test_generator/Assertions.res` and `test_generator/AssertionGenerators.res`, following the guidelines at https://bloodyowl.github.io/rescript-test/assertions. The function should be returned as a string, so that our templating system can inject the code into the generated tests.

BNAndras · 2026-06-08T05:29:51Z


-```shell
-bin/add-practice-exercise -a foobar -d 3 <exercise-slug>
+# auto format files


configlet fmt -u prompts you on formatting the exercise. configlet fmt -uy would auto-confirm the prompt so that'd be the correct invocation for auto-formatting.

BNAndras · 2026-06-08T05:32:03Z

-## Adding exercises
-
-New (practice) exercises can be added via:
+Run the [`fmt` command][configlet-fmt-link] to verify if exercises and configuration files are formatted correctly. Address any issues before pushing your changes:


configlet fmt works specifically on config.json files, nothing else.

BNAndras · 2026-06-08T05:34:12Z

+make test EXERCISE=<exercise-slug>
+```
+
+Run all exercise's tests:


Suggested change

Run all exercise's tests:

Run all exercises' tests:

BNAndras · 2026-06-08T05:35:28Z

+- `exercises/practice/<exercise-slug>/.meta/tests.toml` - if any of these test cases are not relevant to the language, add `ignore = true` on a newline below the description
+- `exercises/practice/<exercise-slug>/.meta/testTemplate.js` - edit this file to allow the test generator to automatically create test files.
+  - you must write your comparator functions - https://bloodyowl.github.io/rescript-test/assertions.
+  - common assertions with comparator functions are located at `test_generator/assertions.js`. Pass the required ones into the `assertionFunctions` array.


Suggested change

- common assertions with comparator functions are located at `test_generator/assertions.js`. Pass the required ones into the `assertionFunctions` array.

- common assertions with comparator functions are located at `test_generator/assertions.js`. Add the ones you'd like to use to the `assertionFunctions` array.

BNAndras · 2026-06-08T05:37:00Z

+
+Tests are written using [rescript-test](https://bloodyowl.github.io/rescript-test/). Follow these steps when writing tests:
+
+- **Filter canonical data:** Open `exercises/practice/<exercise-slug>/.meta/tests.toml`. If a specific canonical test case is not applicable to ReScript, add ignore = true below its description. E.g.


Suggested change

- **Filter canonical data:** Open `exercises/practice/<exercise-slug>/.meta/tests.toml`. If a specific canonical test case is not applicable to ReScript, add ignore = true below its description. E.g.

- **Filter canonical data:** Open `exercises/practice/<exercise-slug>/.meta/tests.toml`. If a specific canonical test case is not applicable to ReScript, add include = false below its description. E.g.

TheRealOwenRees · 2026-06-08T18:59:09Z

I am not certain how to ensure the problem specification is the newest version. Running git submodule update --init --recursive pulls the same version.

BNAndras · 2026-06-08T19:46:39Z

Hmm, I’m not sure to be honest so this will be a learning experience for me. I’ll take a look tonight or tomorrow.

BNAndras · 2026-06-10T04:54:54Z

git submodule update --remote worked for me. We want to grab the latest commit from the submodule's remote which is the upstream problem-specifications repo. git submodule update --init --recursive grabs the commit this repo is pointing to, but that's stale so the CI fails.

BNAndras · 2026-06-10T04:58:25Z

The CI isn't that terribly useful on PRs that don't interact with the problem-specifications submodule so I'll tweak the script so it only fires off in those situations.

TheRealOwenRees added 4 commits March 10, 2026 11:09

improve developer docs in readme

85ba15a

add fork and clone info

96c8cb7

add feedback, copied form ocaml track

466957d

add relevant exercism doc links

54c5e4d

BNAndras reviewed Mar 11, 2026

View reviewed changes

TheRealOwenRees added 4 commits March 12, 2026 12:03

remove repo fork info

aa24d84

update configlet fmt typo

f2d91a4

update installation / prerequisites section

365ff5d

add submodule explanation

3a5f68e

TheRealOwenRees force-pushed the developer-docs branch 2 times, most recently from 9e3f019 to e2f1db1 Compare April 1, 2026 11:02

TheRealOwenRees requested a review from BNAndras June 4, 2026 08:08

BNAndras reviewed Jun 8, 2026

View reviewed changes

TheRealOwenRees added 5 commits June 8, 2026 20:14

moved coding style, deleted docker commented out instructions

ed8bbe4

remove in directly embeded links in preference of references

ab91145

replace reason with rescript in wording

e69d005

Merge branch 'main' into developer-docs

77bb0de

Merge branch 'main' into developer-docs

9b48f6e

TheRealOwenRees force-pushed the developer-docs branch from e2f1db1 to 9b48f6e Compare June 8, 2026 18:46

sync metadata

d167c03


		- Configure the test template: Edit `test_templates/<ExerciseName>_template.res`. Delete and uncomment the code where indicated. Use previous templates as examples of how to achieve what you need. Common comparator functions are found in `test_generator/Assertions.res`

		- Generate and run tests: To build the test file and run it, run `make test EXERCISE=<exercise-slug>`. Your generated test cases are found in `exercises/<exercise-slug>/tests/<ExerciseName>_test.res`. Verify that the test cases accept and return the correct data.


		- Generate and run tests: To build the test file and run it, run `make test EXERCISE=<exercise-slug>`. Your generated test cases are found in `exercises/<exercise-slug>/tests/<ExerciseName>_test.res`. Verify that the test cases accept and return the correct data.

		- Creating new comparator functions: If none of the comparator functions satisfy the exercise's test requirements, you can write a new one in `test_generator/Assertions.res` and `test_generator/AssersionGenerators.res`, following the guidelines at https://bloodyowl.github.io/rescript-test/assertions. The function should be returned as a string, so that our templating system can inject the code into the generated tests.

	- common assertions with comparator functions are located at `test_generator/assertions.js`. Pass the required ones into the `assertionFunctions` array.
	- common assertions with comparator functions are located at `test_generator/assertions.js`. Add the ones you'd like to use to the `assertionFunctions` array.


		Tests are written using [rescript-test](https://bloodyowl.github.io/rescript-test/). Follow these steps when writing tests:

		- Filter canonical data: Open `exercises/practice/<exercise-slug>/.meta/tests.toml`. If a specific canonical test case is not applicable to ReScript, add ignore = true below its description. E.g.

Conversation

TheRealOwenRees commented Mar 10, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Generating Tests?

Updating An Existing Exercise?

Adding A New Exercise?

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TheRealOwenRees Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BNAndras commented Jun 7, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TheRealOwenRees commented Jun 8, 2026

Uh oh!

BNAndras commented Jun 8, 2026

Uh oh!

BNAndras commented Jun 10, 2026

Uh oh!

BNAndras commented Jun 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

TheRealOwenRees Jun 8, 2026 •

edited

Loading