Skip to content

Update docs #371

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
TheRealOwenRees wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Update docs #371

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5e4d9e7
updated broken links
TheRealOwenRees Aug 2, 2025
7cb41fa
remove links to test suites that cannot be found, along with text
TheRealOwenRees Aug 2, 2025
fae15d6
PR link updated
TheRealOwenRees Aug 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,13 @@ Follow the instructions under https://reasonml.github.io/docs/en/installation to

We welcome all contributions, both large and small.

Please read about how to [get involved in a track](https://github.com/exercism/docs/tree/master/contributing-to-language-tracks). Be sure to read the Exercism [Code of Conduct](https://exercism.io/code-of-conduct).
Please read about how to [get involved in a track](https://github.com/exercism/docs/tree/main/building/tracks). Be sure to read the Exercism [Code of Conduct](https://exercism.io/code-of-conduct).
Copy link
Member

@IsaacG IsaacG Aug 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Please read about how to [get involved in a track](https://github.com/exercism/docs/tree/main/building/tracks). Be sure to read the Exercism [Code of Conduct](https://exercism.io/code-of-conduct).
Please read about how to [get involved in a track](https://exercism.org/docs/building/tracks).
Be sure to read the Exercism [Code of Conduct](https://exercism.org/docs/using/legal/code-of-conduct).


Fixes and improvements to existing exercises are welcome. Please note that this track's exercises must conform to the Exercism-wide standards described in the [documentation](https://github.com/exercism/docs/tree/master/language-tracks/exercises). If you're unsure about how to make a change, then go ahead and open a GitHub issue, and we'll discuss it.
Fixes and improvements to existing exercises are welcome. Please note that this track's exercises must conform to the Exercism-wide standards described in the [documentation](https://github.com/exercism/docs/tree/main). If you're unsure about how to make a change, then go ahead and open a GitHub issue, and we'll discuss it.
Copy link
Member

@IsaacG IsaacG Aug 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Fixes and improvements to existing exercises are welcome. Please note that this track's exercises must conform to the Exercism-wide standards described in the [documentation](https://github.com/exercism/docs/tree/main). If you're unsure about how to make a change, then go ahead and open a GitHub issue, and we'll discuss it.
Fixes and improvements to existing exercises are welcome.
Please note that this track's exercises must conform to the Exercism-wide standards described in the [documentation](https://exercism.org/docs/building).
If you're unsure about how to make a change, please post on [the forum](https://forum.exercism.org/).

Copy link
Member

@IsaacG IsaacG Aug 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure how open we are to contributions on unmaintained tracks :)

Copy link
Member

@BNAndras BNAndras Aug 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If there weren’t any contributions, nobody would get the rep to be considered a maintainer candidate. So we shouldn’t actively discourage contributions I think, but we don’t want to actively encourage them either. We’re not the track maintainers who would have a vision of what the track is and needs to be.

Therefore, I’m fine working within what we have now to add practice exercises and update the docs. That doesn’t require a lot of track-specific knowledge on our part. If someone wants to work on the track past that, they should ideally be a track maintainer.

Copy link
Contributor Author

@TheRealOwenRees TheRealOwenRees Aug 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm happy to keep adding lessons and updating the docs if you think it will increase the popularity of the track.

Because there is a lot of overlap between OCaml and Reason, I was thinking about copying some of the parts of the exercise generation and templating from the OCaml track and trying to make it work with the current test runner. This is some time away though if I were to attempt it .

Copy link
Member

@IsaacG IsaacG Aug 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm happy to keep adding lessons and updating the docs if you think it will increase the popularity of the track.

I have no idea how much the number of lessons/exercises influences peoples' interest in joining a track.

Would you like to be a track maintainer?

Because there is a lot of overlap between OCaml and Reason, I was thinking about copying some of the parts of the exercise generation and templating from the OCaml track and trying to make it work with the current test runner.

That sounds like a good idea to me.

Copy link
Member

@BNAndras BNAndras Aug 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Name recognition likely drives the student numbers. In a year, Batch Script gained 1.4k students with only 21 exercises. In nine months, Arturo gained 200 students with 71 exercises.

Most tracks have several dozen exercises implemented now because of the previous 12in23 and 48in23 challenges. Adding exercises won’t make a track stick out nowadays. However, they could help with student retention if the additional exercises cover topics or difficulty levels not adequately covered by existing exercises.

If you want to draw more students in, I’d suggest publicizing the track’s existence and finding an audience. Is there a ReasonML community forum or Discord server perhaps?

Copy link
Contributor Author

@TheRealOwenRees TheRealOwenRees Aug 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The ReasonML track is in a tricky place at the moment. It still uses Bucklescript which is now considered out of date. I don't think it is feasible to promote the track in its current form in places such as the ReasonML Discord server, due to it being outdated.

BuckleScript evolved on its own and became ReScript, whereas the defacto JS build tool for Reason is now Melange. This opens up a whole other conversation, one that has been previously had, about updating the track to use Melange. I know that using Melange comes with its own set of issues, because a reasonble Docker container size was never settled on.

In short, yes I would be intersted in being a maintainer and actively promoting this track. The longer version is that there needs to be a decision made about upgrading the track, using previous contributor's work, before it would be worth commiting me to such responsibilities. I need to look into the work previously done and see what can be done with the Docker image before proceeded.

Perhaps I can look into this over the coming week(s) and report back?

As a side note, I believe that previous discussions centered around renaming this track to Rescript are now invalid. ReasonML and Rescript are now two separate projects, one centered around the OCaml ecosystem, and the other just compiling to JS. There is a different syntax in both languages.

Copy link
Member

@IsaacG IsaacG Aug 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In short, yes I would be intersted in being a maintainer and actively promoting this track. The longer version is that there needs to be a decision made about upgrading the track, using previous contributor's work, before it would be worth commiting me to such responsibilities. I need to look into the work previously done and see what can be done with the Docker image before proceeded.

That would be up to the track maintainer(s) to decide on 😄

Perhaps I can look into this over the coming week(s) and report back?

Absolutely. If you're interested in getting involved as a maintainer, you should post on the forum about that.

Copy link
Contributor Author

@TheRealOwenRees TheRealOwenRees Aug 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In short, yes I would be intersted in being a maintainer and actively promoting this track. The longer version is that there needs to be a decision made about upgrading the track, using previous contributor's work, before it would be worth commiting me to such responsibilities. I need to look into the work previously done and see what can be done with the Docker image before proceeded.

That would be up to the track maintainer(s) to decide on 😄

Perhaps I can look into this over the coming week(s) and report back?

Absolutely. If you're interested in getting involved as a maintainer, you should post on the forum about that.

Understood!

If the Docker image size is not an issue then we can move forward. If not, part of me is wondering if the track should be archived and effort put into building a Rescript track.

Copy link
Member

@IsaacG IsaacG Aug 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have no idea if the Docker image size is an issue or not. Jeremy would need to weigh in on that. I'll ping him on the forum thread.


## Exercise Tests

All Exercism exercises contain a test suite, which help to guide the user's implementation. You can read more about how we think about test suites in [the Exercism documentation](https://github.com/exercism/docs/blob/master/language-tracks/exercises/anatomy/test-suites.md).
All Exercism exercises contain a test suite, which help to guide the user's implementation.

Tests should be written using [bs-jest](https://github.com/glennsl/bs-jest).

Expand Down Expand Up @@ -47,7 +47,7 @@ If you plan to make significant or breaking changes, please open an issue so we

## Submitting a Pull Request

Pull requests should be focused on a single exercise, issue, or conceptually cohesive change. Please refer to Exercism's [pull request guidelines](https://github.com/exercism/docs/blob/master/contributing/pull-request-guidelines.md).
Pull requests should be focused on a single exercise, issue, or conceptually cohesive change. Please refer to Exercism's [pull request guidelines](https://github.com/exercism/docs/blob/main/building/github/contributors-pull-request-guide.md).
Copy link
Member

@IsaacG IsaacG Aug 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Pull requests should be focused on a single exercise, issue, or conceptually cohesive change. Please refer to Exercism's [pull request guidelines](https://github.com/exercism/docs/blob/main/building/github/contributors-pull-request-guide.md).
Pull requests should be focused on a single exercise, issue, or conceptually cohesive change.
Please refer to Exercism's [pull request guidelines](https://exercism.org/docs/building/github/contributors-pull-request-guide).


Please use [refmt](https://reasonml.github.io/docs/en/extra-goodies.html) to ensure a consistent coding style.

Expand All @@ -59,16 +59,16 @@ refmt --in-place Example.re

Before submitting your pull request, you'll want to verify the changes in two ways:

* Run all the tests for the ReasonML exercises. There is a top level Makefile, run: `make`.
* Run checks on the repo using [configlet](https://github.com/exercism/docs/blob/master/language-tracks/configuration/configlet.md). From the top level, run:
- Run all the tests for the ReasonML exercises. There is a top level Makefile, run: `make`.
- Run checks on the repo using [configlet](https://github.com/exercism/docs/tree/main/building/configlet). From the top level, run:
Comment on lines +62 to +63
Copy link
Member

@IsaacG IsaacG Aug 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Run all the tests for the ReasonML exercises. There is a top level Makefile, run: `make`.
- Run checks on the repo using [configlet](https://github.com/exercism/docs/tree/main/building/configlet). From the top level, run:
- Run all the tests for the ReasonML exercises.
There is a top level Makefile, run: `make`.
- Run checks on the repo using [configlet](https://exercism.org/docs/building/configlet).
From the top level, run:


```sh
./bin/configlet lint --track-id reasonml .
```

## Contributing a New Exercise

Please see the documentation about [adding new exercises](https://github.com/exercism/docs/blob/master/you-can-help/make-up-new-exercises.md).
Please see the documentation about [adding new exercises](https://github.com/exercism/docs/tree/main/building/tracks/practice-exercises).
Copy link
Member

@IsaacG IsaacG Aug 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Please see the documentation about [adding new exercises](https://github.com/exercism/docs/tree/main/building/tracks/practice-exercises).
Please see the documentation about [adding new practice exercises](https://exercism.org/docs/building/tracks/practice-exercises).


Note that:

Expand Down