Make errors more idiomatic, following Roc best-practices

[ageron]

Following a discussion on Roc's Zulip Chat, we decided that the errors should be treated in a more idiomatic way, to teach best practices to the students.

When an error occurs, the recommended return value is:Err (SomeDescriptiveTag someArgs), where someArgs contains all the information needed for the error handling code, as plain data (not English text, as this is not machine-friendly, and it does not play well with internationalization when displaying a message to the user).

If the problem is due to a bad argument, then SomeDescriptiveTag should indicate which one(s) and use the past tense, for example NumberArgWasNotPositive.

So an idiomatic error would look like Err (NumberArgWasNotPositive -5), NOT Err "The number -5 was not positive".

[github-actions]

This PR touches files which potentially affect the outcome of the tests of an exercise. This will cause all students' solutions to affected exercises to be re-tested.

If this PR does not affect the result of the test (or, for example, adds an edge case that is not worth rerunning all tests for), please add the following to the merge-commit message which will stops student's tests from re-running. Please copy-paste to avoid typos.

[no important files changed]

For more information, refer to the documentation. If you are unsure whether to add the message or not, please ping @exercism/maintainers-admin in a comment. Thank you!

[isaacvando]

@ageron This is a nice way to show this style of error handling!

I think it would be good to avoid asserting that the errors contain specific payloads in the test cases. When the payload is included in the assertion, a user could write a fully functional solution that doesn't pass some of the tests because it returns error tags with different names or payloads. I don't think that a different approach to error handling by the solution should count as the solution being incorrect. To keep the richer error tags in the examples, the assertions could be updated to result |> Result.isErr instead.

[ageron]

Thanks @isaacvando !

I see your point, but tbh I quite like the fact that the exercises require a specific error: I see it as a learning opportunity for the students.

I was personally drawn to Roc specifically for its error management: I've always dreamt of a language that would have safe, granular, and yet convenient error handling. I don't know any other language that handles errors as well as Roc, so I think it's a good idea to demonstrate how it works.

As a point of reference, I looked at 10 other tracks:

• 1 of them (C#) checks the exception type without checking the details.
• 4 of them (Elm, Rust, C, Haskell) just expect Nothing, None or false.
• 5 languages (Python, Javascript, Bash, Java, Typescript) expect a detailed error.

My takeaway from this little exploration is that we're pretty free to do what we think is best for our language. I'm happy to discuss this further on Roc's Zulip chat, to see what others think.

Side note: only about 20% of the exercises have test cases for errors anyway.

[isaacvando]

@ageron Good points, works for me!

[Anton-4]

The CI error is likely due to using the latest nightly, it requires basic-cli 0.15.0 instead of 14. Merging in main should fix this.

[ageron]

This conversation started a debate on Roc's Zulip Chat. As a result, here's the latest strategy for handling error test cases:

• The test cases for errors should be minimal, just Result.isErr result. This gives the user the freedom to implement errors in any way they choose.
• The annotations in the stub exercise file of each exercise (e.g., exercises/practice/wordy/Wordy.roc) also do not require a specific type of error, the user is free.
• The example solution (e.g., exercises/practice/wordy/.meta/Example.roc) suggests a detailed error. That said, this file only seems to be used to ensure that the test cases work as expected. They don't seem to be shown anywhere on exercism.org, so it's probably not a big deal what kind of errors we use there, except perhaps for the very curious user who might look at the track's code on github.