Contributing to GDQuest projects

If you want to become a Free Software contributor and be part of our projects, this is the place to get started!

This guide will tell you everything you need to know to get your improvements integrated into the projects as fast as possible.

We use these guidelines at GDQuest as well to work efficiently together.

To make it a smooth and pleasant experience for everyone working together, we’ll ask you to:

1. Communicate. Let people know what you’re working on, join discussions on the issues tracker, and open your own issues!

2. Be mindful of the contributors' and the maintainers' time. Most people are helping benevolently. Help us all save time by writing precise bug reports and feature requests.

3. Be kind and supportive. We’re building a welcoming community and want to get people to work together. 🙂

In short

We ask everyone to follow 3 steps to work smoothly and productively together:

1. Communicate beforehand

   • Open an issue on GitHub before you code a new feature or make a big change.

   • Reply to issues you’d like to tackle. Ask any info you need to make it work within the project’s design and scope.

2. Follow the code style guide

   • We designed it to keep the code clean, easy to read, and consistent.

3. Create neat Pull Requests

   • Writing a clear title and commit only relevant changes. This takes no time at all, but it helps everyone else quite a lot!

/Every one of us is responsible for making work go smoothly for everyone else. Let’s keep in touch with one another, be kind to one another, write great code, keep the project’s scope and design targets in mind, and create clean pull request./

How to communicate well as a contributor

We want to build a friendly and a welcoming community at GDQuest. One that is inclusive for everyone, regardless of our experience, origins, or opinions. We should do our best to get newcomers to want to learn more about Free Software and become contributors.

We have one key rule when we talk to one another: be kind and supportive.

You can find more details about it in our Communication Guidelines. They’re based on the GNU project’s Kind Communication Guidelines.

Help us help you

Review work is time-consuming. By communicating upfront, letting us help you as you contribute, and respecting the code style that we all use, you can save both yourself and the reviewers a lot of time.

In short, you should explain the problem that you are trying to solve and the way you intend to solve it before you get started on the issue tracker. We likely have code in place already and ideas to keep your code simple which can save you a lot of work!

We are here to review your Work-in-Progress (WIP) code, to help if you have any trouble with the git workflow, or if you get stuck along the way.

If you want to work on an open issue, make sure that you understand it well by asking for all the information you need in order to tackle it efficiently.

You can also get in touch on the GDQuest Discord server.

Code style

There are many ways to structure code and many ways to solve a given problem. Thus it’s important that we follow the same guidelines so our code remains easy to read and to maintain. We chose code styles that are accessible to other developers, so we can build great projects together.

These guidelines are separate guides:

1. Godot GDScript: best practices

2. Blender Python: best practices

Before you write your own code, read the existing code in the project to get a sense for the style and architecture. We write docstrings in our code to help you understand the purpose of different classes and functions/methods.

How to create great Pull Requests

Commit guidelines

Poor commit titles and messages make it harder to maintain the project as it grows. The code history becomes hard to read, so nobody wants to dive into it anymore.

That’s why we ask you to write clear git messages when working on our repositories, by following these few guidelines:

1. Separate subject from body with a blank line
2. Keep the subject line under 72 characters
3. Capitalize the subject line
4. Do not end the subject line with a period
5. Use the imperative mood in the subject line
6. Wrap the body at 72 characters
7. Use the body to explain what and why vs. how

These guidelines come from the great article How to Write a Git Commit Message by Chris Beams. Read it for detailed insights.

Summarize changes in around 50 characters or less

More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. In some contexts, the first line is treated as the subject of the commit and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); various tools like log, shortlog and rebase can get confused if you run the two together.

Explain the problem that this commit is solving. Focus on why you are making this change as opposed to how (the code explains that). Are there side effects or other unintuitive consequences of this change? Here’s the place to explain them.

Further paragraphs come after blank lines.

• Bullet points are okay, too

• You can use hyphens to represent list items

If you use an issue tracker, put references to them at the bottom, like this:

Closes: #123 See also: #456, #789

When you open a pull request git will automatically use the title and body from your last commit. So you can and you should use the commit to communicate your changes clearly. Doing so will make the review easier and faster.

Some examples of good commit messages:

Add life bars for the monsters 
Fix the character getting stuck in the wall
Redesign level 3
Improve performances in the level loader class

Some examples of what not to do:

Added UI
Update
New Monsters were added

Create meaningful commits

Squash your commits!

When you are working on your computer and local fork, you may use as many commits as you want so that you can jump back in your code’s history. But once you publish your own changes and submit your pull request, you should squash your commits so that the project’s history stays easy to browse.

Squashing is the process of taking several commits and merging them back into one.

You can find a good way to squash your last commits together on this stack exchange answer.

A new feature can be a single commit. A bug fix or an improvement can be one commit. A commit can range from a small change to hundreds of lines of code at times. It should just be a clear and a coherent step in the project’s history.

How to write great bug reports and requests

When you report a bug or request a new feature or an improvement, we need information to fix it.

Writing a great bug report

Finding and fixing bugs can be time-consuming. if you help us spot the bug and reproduce it faster than we could on our own, we can in turn respond and solve it quickly:

1. Provide a list of actionable steps to reproduce the bug

2. Provide the version of the project, of the program, e.g. Godot 3.1, and the operating system you are working with

3. If the program prints an error in the console, copy it as text (preferable) or take a screenshot

4. Tell us what result you expect to get instead

On GitHub, you can surround code or error messages with triple back-ticks: ``` to create a code block:

Three backticks surround this line of text

Here is an example of a great bug report:

1. The title describes the problem clearly

2. The body includes all the steps to reproduce the error

3. There is a traceback to help track down the bug faster

4. (optional) The issue includes a minimal example project to quickly reproduce the error

   • If there are multiple steps to produce the bug, or it happens with a particular setup, a demo is more than welcome! It will allow us to fix the bug faster

5. (optional) Include a screenshot or a short video recording

   • Very useful if the issue is visual in nature, if it doesn’t produce a crash, or an error message

When you make a request for improvements or new features, please always describe the problem that you are facing and your needs. To produce a great design, we need to understand your problem and to explore different solutions:

1. We need to understand the problem to figure out the details of the design and how to best structure our code

2. Copying what other programs do without doing any research is the best way to produce incoherent design and a missed opportunity to create more efficient tools

3. The solution you envision may be too time consuming or too complicated to code

4. We might already have tools in place that solve your problem that are just not visible enough. In this case, we can improve the user interface, improve an existing tool, or create a tutorial to solve your problem

Here is an example of a great feature request:

1. The title sums up the request well

2. The body describes the problem or the need the request intends to solve

3. There’s an example of how it’s done in another application to give some more context about what the user expects

Taking screenshots

If you are on Windows, I highly recommend ShareX, an amazing open source program. It lets you take annotated screenshots, animated GIFs, and video clips. On Linux, you can use the built-in tool in your distribution: screenshot on Ubuntu, Spectacle on KDE…