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:
We ask everyone to follow 3 steps to work smoothly and productively together:
/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./
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.
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:
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.
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
rebasecan 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
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.
When you report a bug or request a new feature or an improvement, we need information to fix it.
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:
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:
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:
Here is an example of a great feature request:
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…