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!! :)

[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]

This could use some information about how one might activate the debug server.

Also, is it checking/verifying the syntax or highlighting it? The godot-tools page describes syntax highlighting, and those are different things.

[codingthat]

I guess it just needs rewording: Having Godot running (with a project open, as mentioned) is how one activates the debug server. There's no additional step.

It does both, and more, I think, depending on what checking/verifying is considered to cover. For example, if I add a duplicate return statement, it does this:

[BNAndras]

Yeah so it's doing some sort of static analysis then. That's fine.

We could just link to the godot-tools docs and have the students follow up the official setup there including keeping Godot running. That keeps things focused on installing and getting Godot set up for Exercism use.

[codingthat]

Done, cf. 107e961

[codingthat]

Ah, sorry, I didn't see your message before writing that.

We could, but actually their official documentation seems incorrect on that point:

Make sure the Godot editor is running
Make sure to open the project in the Godot editor first. If you opened the editor after opening VS Code, you can click the Retry button in the bottom-right corner in VS Code.

The specific project doesn't need to be open. Any project will do. No need to keep the Godot editor paralleling your exercises—just open something and forget about it. So maybe leaving our note (now that I've improved the wording, that is) will be helpful to learners?

[codingthat]

@BNAndras What do you think, is it OK to leave the note after all, since it's more accurate than the official docs? I'm still seeing the wording I quoted e.g. at https://marketplace.visualstudio.com/items?itemName=geequlim.godot-tools

[BNAndras]

Seems fine. I might tighten up the prose a little like this:

To get GDScript syntax highlighting inside an editor like [Visual Studio Code][vscode], you'll need an extension such as [godot-tools][godot-tools] installed plus a running debug server.
Godot starts this debug server automatically whenever a project is open in its own editor and keeps it running until the project or Godot itself is closed.

[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.