template-godot4/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 for linting & formatting, respectively.

These tools are integrated into our development workflow using Godot plugins: ryan-haskell/gdformat-on-save and 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:

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

Next, install gdscript-toolkit through pip:

$ 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

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:

$ git config core.hooksPath .githooks

Standards & Practices

Style

Code should generally conform to the GDScript style guide where possible. Use the provided linter and formatter 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 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.
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 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.