Contributing - endlessm/threadbare GitHub Wiki

We welcome contributions to Threadbare! This document lays out some of the requirements for a contribution to be expected. There is a corresponding document for Reviewing Contributions.

Please see the separate Licensing documentation. This is more important than anything else in this document. If your contribution uses code or assets under an unsuitable license, we cannot accept it, even if it meets the other requirements below.

(By contrast, the maintainers can normally fix suitably-licensed contributions if they don't quite meet the requirements below.)

In-game text and dialogue for the main storyline should be written in English, for translation into other languages. Text and dialogue in StoryQuests may be written in another language if preferred.

Prefer US English spellings for in-game text and dialogue, as well as source code, comments, and pull request descriptions:

• “Color”, not “colour”
• “Traveler”, not “traveller”

Use “dialogue” when referring to in-game speech (following the DialogueManager API), but “dialog” if referring to a dialog box.

GDScript source code should follow the GDScript style guide. This is enforced using gdlint and gdformat from godot-gdscript-toolkit when changes are submitted to the project.

You can use prek to run the same checks locally.

Follow the prek installation instructions for your OS, if you don't already have it installed.

Run the following command in your Threadbare checkout to set up prek as a git hook:

prek install

Now, coding style checks will be enforced when you run git commit.

We prefer to reference nodes in scripts by their Unique Name. In the Scene tree dock, right-click on the node and select Access as Unique Name in the context menu. Suppose we have a node named "HitBox" of type Area2D. With unique name, dragging and dropping the node from the Scene tree to the Script will paste %HitBox, and doing drag & drop while the Ctrl key is pressed will paste the line:

@onready var hit_box: Area2D = %HitBox

Which is very useful.

To make it easy to find the the .tscn file, leave it as the only file in the folder and move all related scripts or resources to a components/ subfolder. Example:

• scenes/game_elements/characters/npcs/cat/cat.tscn
• scenes/game_elements/characters/npcs/cat/components/cat.png
• scenes/game_elements/characters/npcs/cat/components/cat.tres
• scenes/game_elements/characters/npcs/cat/components/pet_interaction.gd

Exceptions:

• For reusable assets, use the assets/first_party/ or assets/third_party/ folders instead.
• For reusable scripts, use the scenes/game_logic/ folder instead.

Godot supports UTF-8 characters in filenames, in node names, and even in code (in names of classes, functions, variables, properties). However, the filters in the Filesystem dock, Scene Tree dock, and others do not support fuzzy matching. This means that an asset named "Muñeco_de_paja.png" or a scene file named "el_umbral_del_sueño.tscn" won't be easy to handle by other developers. So please avoid characters that won't be available in all keyboards.

Pull requests should have:

• A short title describing the intent of the change. The title should be in the imperative mood and formatted in sentence case (i.e. with a leading capital letter) but no trailing full stop or other punctuation mark. If appropriate, prefix the title with the component being modified.

• One or more paragraphs explaining the change in more detail.

• If the pull request resolves an issue, link the pull request to the issue with a line like this at the end of the description:

  Resolves https://github.com/endlessm/threadbare/issues/XYZ

  If the pull request relates to an issue without resolving it, include the issue link but not the Resolves keyword.

Here is an example:

Ink combat: Add ink follow player feature

The ink can now have a Node2D to follow. A constant force in that node direction will be set every frame.

The enemy has a boolean export to throw ink that follows the player node (the first and only node that should be in the "player" group).

Resolves https://github.com/endlessm/threadbare/issues/71

Your pull request will be squashed into a single commit when it is merged, and the title and description of the pull request will be used as the commit message. If you want to make several separate changes, open a separate pull request for each one. This is subjective, so use your judgement!

These articles and presentations give more background on how and why to craft a good commit message:

• How to Write a Git Commit Message by cbeams
• Telling Stories Through Your Commits by Joel Chippindale
• Git (and how we Commit) Christian Grøngaard
• Scoped Commits by Sumner Evans / Nevarro LLC

Some projects, following the Conventional Commits specification, like to add a prefix such as fix:, feat:, chore:, etc. to commit messages. Threadbare does not use this convention.

When discussing code in issues or PR comments, please use text rather than screen captures. If unsure, open a pull request as draft to start a conversation. Is hard to comment about programming code without the ability to copy-paste text or compare using diff.

Contributions that don't go directly to the game repository are welcome too! Examples:

• Concept art for a new enemy.
• Concept for a new level design.
• Tutorial explaining how to do pixel art for Threadbare.
• Mockup of a new cutscene.
• A piece of lore narrative.
• A new sound effect.
• A new sprite.

They should be delivered in GitHub, as comments or attachments. Please don't rely on external websites for sending files. This has some constraints though. Check https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/attaching-files for the existing constraints. Talk to maintainers if you can't attach your contribution. Also you can check how others did it in Contributed artwork.

If multiple people have contributed to a single change, special care must be taken to make sure they each receive credit for their work. If a pull request is made up of several commits, with different authors, this is sufficient. But if all commits on a pull request are made by the same person, the other contributors must be identified with a specially-formatted tag in the pull request description, as described in GitHub's Creating a commit with multiple authors guide. In brief, if Jane Doe submits a pull request to add a new enemy, with original art created by Alice Jones, the pull request description should end with:

Co-authored-by: Alice Jones <[email protected]>

If you're not sure how to do this, the Threadbare maintainers will be happy to help.

In Reviewing-a-StoryQuest-submission#giving-credit-to-multiple-learners there is a command to obtain the line for any GitHub user given.