Contribution process

In this page we document the process by which the developers of the project collaborate and get things done. If you're interested in contributing or getting involved please consider the guidelines and tips that are outlined in this page. Please check-in often as we flesh out this document further.

Introduction

The first thing contributors and developers have to do is introduce themselves to the community. We'd like to have all contributors involved in the decision making process with regards to the development of GCompris.

If you haven't yet, please subscribe to the GCompris mailing list and introduce yourself before proceeding.

Merge / Pull Request

The maintainers of the project review and Merge Requests (Known as Pull Request on GitHub) from contributors. This allows the project to move forward using the Git distributed development workflow. If you need an introduction to git, please refer to the following links for git-specific information.

   ProGit — a website dedicated to basic and advanced git usage.
   GitHub Git Setup — the GitHub help pages on setting up git to work with GitHub.

What follows in this section assumes that you're already familiar with the basic git workflow.

Which Repo should I use

The official repository on invent.kde.org requires a KDE developer account. We will ask regular contributors to get an account and work on the KDE repository.

Before that, the best way is to send us a diff with your changes, using phabricator.

For developers interested only in small and occasional contribution, a push request from github can be accepted.

Forking the Repo

Forking requires that you already have an account. Before you can submit Merge or Pull Requests you should first create your own fork of the repository. You can fork the repository by clicking on the Fork button on the repository page.

Asking for a Review Request

After creating a Diff to ask for a review on phabricator, please always edit it to add the corresponding group in Reviewers (it can be GCompris, GCompris:Bugs, GCompris: Improvements, ... please select the most appropriate one for your patch).

Also, please always send screenshots showing your changes (one before and one with the changes). This will help us to notice quickly any big issue, and to understand easily what is the goal of the patch.

Preparing a Merge / Pull Request

Once you have a fork of the repo, determine to which branch you'd like to send a Merge / Pull Request to. In the next section we describe the various branches we'll be dealing with in the course of development of a release.

When you've determined the branch to which you'd like to send a Merge / Pull Request to you can follow these steps to prepare your change for inclusion in GCompris.

1. Create an integration branch. This integration branch should be rooted off the branch you intend to send a request to. For example, if you're sending a Merge / Pull Request to gcompris/master and your fork is user/master, you should create a user/master-integration branch.
2. Create a topic branch. From the integration branch, you can then create as many topic branches as you want. It's recommended that you isolate all experimentation to branches — once you're reasonably sure that your work is good to go, merge your topic branch into the integration branch in your local repo, then push the changes to your KDE or GitHub repo.
3. Make sure your integration branch is up to date. To do this you should first pull changes to your local master (assuming that's where you'd like to send a pull request to), rebase your integration branch to the tip of master, then make sure all merge conflicts are dealt with. Proceed only when your integration branch is up-to-date with the official branch you're going to send your Merge / Pull Request to.
4. Send the Merge / Pull Request. Once you're reasonably happy with the state of your integration branch, send off a request to the official repo and set the destination branch as the branch you intend to send the change to.
5. Address Comments The maintainers will be reviewing your changes, and sometimes they may have comments they will ask you to address in your request. You can do this by going back to the second step of this process, but you don't need to send another request -- all you have to do is push your changes to your hosted integration branch and your request will be updated automatically. That said, don't forget to update the discussion on the request that you're ready for the request to be reviewed again.
6. Your request is merged. If you've done everything correctly up to this point, your request should be cleanly merge-able into the branch you sent the request to. A maintainer will merge your change into the project and you're now officially a contributor to the project!

In case you have multiple requests in flight, you may want to have multiple integration branches — that is, one integration branch per request should be good to keep.