Add track installation instructions #97

codingthat · 2025-04-30T13:44:35Z

No description provided.

meatball133 · 2025-04-30T20:57:20Z

docs/INSTALLATION.md

@@ -1,15 +1,15 @@
 # Installation

-<!-- TODO: write document
+## Installing Godot Engine


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.

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?

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.

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)?

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.

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?

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

docs/INSTALLATION.md

BNAndras · 2025-07-16T20:51:04Z

docs/INSTALLATION.md


-  This document should describe what the student needs to install
-  to allow working on the track on their local system using the CLI.
+The GDScript track is built on top of [Godot Engine][godot-engine], which runs on Windows, Linux, macOS, and Android.


This implies a student can solve exercises locally on those platforms, but we're later saying you need to run the test runner which apparently is Linux-only. So we should be clear upfront about this perhaps with an Exercism caution block so the student doesn't get frustrated after installing Godot locally.

Great point! @meatball133 mentioned the possibility of providing a PowerShell equivalent to the local test runner, but since it depends on run.sh from the test runner repo, we'd need a PS equivalent there as well. (Is it OK if I were to add a PowerShell todo to the GitHub issue tracker?)

Anyway, I will fix the wording here soon.

Done, cf. 107e961

BNAndras · 2025-07-16T20:53:45Z

docs/INSTALLATION.md

+You'll need [Godot installed][installation] correctly to use the test runner.
+
+To build and test GDScript scripts for Exercism, Godot will be run in "headless" mode from the CLI.
+These instructions currently require Linux and bash.


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

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.

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.

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

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"?

BNAndras · 2025-07-16T20:57:14Z

docs/INSTALLATION.md

+
+### Step 2: Downloading the single-exercise test runner script
+
+Assuming you have the `exercism` tool set up and have downloaded at least one GDScript exercise, it should have created an `exercism/gdscript` folder to house the exercises.


The exercism tool hasn't been previously mentioned so we can't assume students have done any of this. We should link to the the CLI installation guide and then provide a description of how to find that exercism/gdscript folder in case the student doesn't know where to find it.

Done, cf. 107e961 and c82456f .

BNAndras · 2025-07-16T21:01:26Z

docs/INSTALLATION.md

+
+## Using an IDE
+
+For syntax checking of GDScript files from, for example, [Visual Studio Code][vscode], you'll need to keep the Godot GUI running with a project open in order to activate the debug server, and an extension like [godot-tools][godot-tools] installed and activated.


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.

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:

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.

Done, cf. 107e961

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?

- Linux requirement for local test runner - Syntax highlighting "etc." - Requirements for keeping a debug server running

Add track installation instructions

8fd6f0b

meatball133 reviewed Apr 30, 2025

View reviewed changes

codingthat added 2 commits May 1, 2025 13:37

Inline refs and single-sentence-per-line

07cdb3c

Include test setup instructions

444cd35

meatball133 reviewed May 1, 2025

View reviewed changes

docs/INSTALLATION.md Show resolved Hide resolved

meatball133 reviewed May 1, 2025

View reviewed changes

docs/INSTALLATION.md Show resolved Hide resolved

meatball133 reviewed May 1, 2025

View reviewed changes

docs/INSTALLATION.md Show resolved Hide resolved

BNAndras reviewed Jul 16, 2025

View reviewed changes

codingthat added 3 commits July 17, 2025 14:48

Add clarifications:

107e961

- Linux requirement for local test runner - Syntax highlighting "etc." - Requirements for keeping a debug server running

Merge branch 'exercism:main' into add-installation

47b1f52

Fix exercism workspace location

c82456f


		### Step 2: Downloading the single-exercise test runner script

		Assuming you have the `exercism` tool set up and have downloaded at least one GDScript exercise, it should have created an `exercism/gdscript` folder to house the exercises.


		## Using an IDE

		For syntax checking of GDScript files from, for example, [Visual Studio Code][vscode], you'll need to keep the Godot GUI running with a project open in order to activate the debug server, and an extension like [godot-tools][godot-tools] installed and activated.

Uh oh!

Add track installation instructions #97

Are you sure you want to change the base?

Add track installation instructions #97

Uh oh!

Conversation

codingthat commented Apr 30, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codingthat May 1, 2025 • 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!

meatball133 May 1, 2025 • 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!

codingthat May 1, 2025 • 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!

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!

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!

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

codingthat May 1, 2025 •

edited

Loading

meatball133 May 1, 2025 •

edited

Loading

codingthat May 1, 2025 •

edited

Loading