Add track installation instructions

[codingthat]

No description provided.

[meatball133]

The idea here is that these should be instructions to setup the language for local testing. If it is meant that users should be using docker for testing then these docs should describe how to setup that for different os.

[codingthat]

I'm not sure it's about testing, per se — there's both docs/TESTS.md and exercises/shared/.docs/tests.md for that, hence my WIP branch for those.

The spec and example for this docs/INSTALLATION.md seem to point more to just installing Godot itself, no?

[meatball133]

It is supposed to tell you how to install so you can test the tests locally.

I mean in most cases, say Python. You would install Python and then you could install the library needed and then simply run pytest and you would get the output. And some languages doesn't need any dependencies at all and have everything built in. So for Godot, if you need like a bash script for it to work. Then these instructions should tell you how to install that script for example.

[codingthat]

OK, fair enough — but then what goes in TESTS.md for Godot? Should it just point back to INSTALLATION.md because there's nothing else to say like other tracks might (skipped tests, etc.)? Or duplicate its info (doesn't sound ideal, but then again, there's explicit mention of doing that for resources vs. help)?

[meatball133]

So the difference between installation and tests is that installation says what/how you install to tests. But tests say how you test. So for python would that be something like:

INSTALLATION.md:

• How to install python
• How to install libraries

TESTS.md:

How to test e.g:

Find the folder with the exercise then cd into that folder

cd path/exercise

Then you have to call pytest.

[codingthat]

OK, so, I will (once we agree on how the testing scripts should look, and finish them) move my WIP stuff so most of it is in this file. However, I'm not sure that's the correct move, because then there's not a real distinction between TESTS.md and the shared tests.md.

Here's what seemed to jive with the general track info docs as well as the comments in the templates:

• INSTALLATION.md: about installing the tech itself (basically a link to the official docs plus a note about which version makes sense for Exercism) (note: nothing about tests)
• TESTS.md: how to install local test runner infrastructure
• shared tests.md: how to run local test runner infrastructure

And actually it's interesting you use Python as an example, because https://exercism.org/docs/tracks/python/installation is not at all about testing. Then its TESTS.md says e.g. how to install pytest. (Then I assume its shared tests.md it how to run tests for a single local exercise.)

However, it does seem that the "how to run a test" part is duplicated from the shared tests.md to the overall TESTS.md.

Either way, I think I did do the non-test installation instructions correctly in the end. OK to merge the current PR?

[codingthat]

@meatball133 when you have a moment, let me know if this part is OK. Thanks!! :)

[codingthat]

@meatball133 ? :)

[BNAndras]

Are we sure this requires just Linux? My Mac has /opt available and it can run Linux-based Docker images.

[codingthat]

I have no Mac to test on, but if it can be verified to work there we can change it. The local test runner described in this doc, though, doesn't use Docker (it relies on run.sh, which runs Godot directly), so you'd have to install Godot.

[BNAndras]

Ah, we might want to call the local test runner something else. Within Exercism, a test runner is almost always the online one. That'll certainly cause some confusion down the line for example if a student is asking about running the local tests and we all think they refer to the online test runner.

[BNAndras]

I have access to a M1 Mac so I can check this script out later this week.

[codingthat]

I see some places I've called it simply "test runner" and I could make it "local test runner" to be unambiguous. But if you think that will still be confused with the online one despite "local" everywhere, I'm open to suggestions. I see other tracks don't generally need one because the CLI syntax for testing is a bit more standardized than in the Godot ecosphere.

Maybe "local solution checker"?

[codingthat]

@BNAndras what do you think?

[BNAndras]

Works fine for me on a Mac.

(base) ➜  darts git:(main) ✗ ./test-local-gdscript-solution.sh
Godot Engine v4.7.stable.official.5b4e0cb0f - https://godotengine.org

-> test_missed_target
-> test_on_the_outer_circle
-> test_on_the_middle_circle
-> test_on_the_inner_circle
-> test_exactly_on_center
-> test_near_the_center
-> test_just_within_the_inner_circle
-> test_just_outside_the_inner_circle
-> test_just_within_the_middle_circle
-> test_just_outside_the_middle_circle
-> test_just_within_the_outer_circle
-> test_just_outside_the_outer_circle
-> test_asymmetric_position

Exercise passed!  Nicely done!

As for the terms, this gets complicated because normally what gets written in these cases is a testing library that the online test runner hooks into but still can be run locally separately from the test runner. However, in this specific case we're using a script to run the test runner locally so it's the same experience whether you're in the online editor or working locally. I guess it really is just the test runner so maybe the best we can do here is consistently specify local test runner vs. online test runner.

[BNAndras]

If we're using a custom testing setup, I strongly recommend that this file be provided to students during the initial download for each exercise. That's what we do on other tracks with custom testing libraries like Red and Scheme. Downloading it afterwards as a separate step runs the risk of confusing students. If I'm downloading the files to work offline, my general expectation would be I can start working with minimal fuss.