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:
- Communicate. Let people know what you’re working on, join discussions on the issues tracker, and open your own issues!
- 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.
- Be kind and supportive. We’re building a welcoming community and want to get people to work together. 🙂
We ask everyone to follow 3 steps to work smoothly and productively together:
- 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.
- Follow the code style guide
- We designed it to keep the code clean, easy to read, and consistent.
- 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.
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:
- Godot GDScript: best practices
- 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
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.
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. 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:
- Provide a list of actionable steps to reproduce the bug
- Provide the version of the project, of the program, e.g. Godot 3.1, and the operating system you are working with
- If the program prints an error in the console, copy it as text (preferable) or take a screenshot
- 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:
- The title describes the problem clearly
- The body includes all the steps to reproduce the error
- There is a traceback to help track down the bug faster
- (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
- (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:
- We need to understand the problem to figure out the details of the design and how to best structure our code
- 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
- The solution you envision may be too time consuming or too complicated to code
- 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:
- The title sums up the request well
- The body describes the problem or the need the request intends to solve
- There’s an example of how it’s done in another application to give some more context about what the user expects
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…
I'm a courteous game designer, with a taste for open source. I'll share all I know.