heliostat/DEVELOPMENT.md

# DEVELOPMENT.md

This is a set of general guidelines for developers.

## Dev Tools

This project uses `gdlint` and `gdformat` from
[Scony/godot-gdscript-toolkit](https://github.com/Scony/godot-gdscript-toolkit)
for linting & formatting, respectively.

These tools are integrated into our development workflow using Godot
plugins:
[ryan-haskell/gdformat-on-save](https://github.com/ryan-haskell/gdformat-on-save)
and
[krampus/gdlint-plugin](https://git.of.the.spectacle.lol/krampus/gdlint-plugin)
respectively.

When a script is saved in the Godot editor, it is automatically
formatted and checked for linting errors which are shown as warnings.

### Setup on Linux Environment

`gdlint` and `gdformat` require Python >=3.8. On Ubuntu:

```bash
$ sudo apt update
$ sudo apt install python3 python3-venv
```

Next, install `gdscript-toolkit` through `pip`:

```bash
$ pip install --user -r requirements.txt
```

Then run `godot`. The plugins should be configured automatically.

(If you prefer to install `gdscript-toolkit` in a venv, just make sure
the plugins can find their required binaries.)

### Setup on Windows Environment

Download and run the appropriate installer from the [Python website](https://www.python.org/downloads/windows/)

During installation, select the "Add python.exe to PATH" checkbox when prompted.

Open "Windows PowerShell" and run the following command to make sure pip is installed:
```
pip --version
```

Assuming pip is installed you should see a message like:
```
pip 24.0 from C:\Users\dummy\AppData\Local\Programs\Python\Python312\Lib\site-packages\pip (python 3.12)
```

If pip is installed, run the following command to install the toolkit for the linter and formatter:
```
install gdtoolkit==4.2.2
```

Then run the following command to finish the installation process:
```
pip install setuptools==69.5.1
```

Check that everything installed by running "gdlint -h" and you should see something like:

```
GDScript linter

A tool for diagnosing typical GDScript code problems.
On success and the exitcode is 0.
On failure, python exception or list of problems is shown and exitcode is non-zero.
...
```
Also run "gdformat -h" and you should see something like:

```
GDScript formatter

Uncompromising GDScript code formatter. The only configurable thing is
max line length allowed and tabs/spaces indent. The rest will be taken
care of by gdformat in a one, consistent way.
...
```

### Git Hooks

If you like, you can use the included githooks to automatically check formatting & linting before making a commit.

You can enable our githooks like this:

```bash
$ git config core.hooksPath .githooks
```

## Standards & Practices

### Style

Code should generally conform to the [GDScript style
guide](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_styleguide.html)
where possible. Use the provided [linter and formatter](#dev-tools) to
apply most style guidelines automatically.

### Type Annotations

Use explicit type annotations wherever possible. Don't fret about it
too much, this is GDScript and there are a lot of situations where you
gotta do some freaky duck typing, but try to do as much explicit type
annotation as you can.

### Organization

_NOTE update this section as we build out the project more_

- All non-code assets go under `assets`
  - Graphical assets go under `assets/images`
    - Sprites go under `assets/images/sprites`
  - Audio assets go under `assets/audio`
    - Music goes under `assets/audio/music`
    - SFX assets go under `assets/audio/sfx`
  - Video assets go under `assets/video`
- Scenes and GDScript source files go under `src`
- Godot plugins go under `addons`

## Git Workflow

We use a standard branching workflow. Here's the full process of getting something merged in:

1. [Create an issue](../../../issues/new) for the feature you want to
   implement or the bug you want to fix, and assign it to
   yourself. Alternately, pick an existing issue you want to work on
   from the [issue tracker](../../../issues).
2. In your local repo, create a new branch off of `main`. Your feature
   branch's name should include the issue number and a brief
   descriptive title, e.g. `37-immanentize-eschaton` or similar.
3. Build the feature or fix the bug or whatever it is you're
   doing. Frequent, small commits are preferred, and it's a good idea
   to merge new changes from `main` often.
4. Push your changes to the server and
   [create a pull request](../../../compare/main...main) to merge your
   feature branch into `main`. Your PR description should include the
   changes you made. If you include the phrase _"closes #[issue
   number]"_ in your PR description, the issue will automatically be
   closed when your PR is merged, which is nice.
5. Request review from `intrusive/Owners`. If your patch touches
   something you think a specific dev needs to see, tag them for
   review explicitly.
6. Once your PR gets approval from either 1 member of
   `intrusive/Owners` or from the specific developer who needs to see
   it, merge it into `main` yourself. There should be a button on the
   PR page to do this. If it says you can't merge automatically, you
   probably need to merge new changes from `main`
7. If it wasn't done automatically, close the issue and delete the
   feature branch.

Try to stick to the above workflow as much as you can, but occasional
shortcuts for hotfixes etc aren't the end of the world.