3. Development Process

As common in open source projects, contributions of code and documentation to the project are highly appreciated. The QGIS community is very supportive. This section describes the procedure for developing and merging your contributions in the QGIS project.

3.1. A git based project

The complexity of the QGIS source code has increased considerably during the last years. Therefore it is hard to anticipate the side effects that the addition of a feature will have. In the past, the QGIS project had very long release cycles because it was a lot of work to reestablish the stability of the software system after new features were added. To overcome these problems, QGIS switched to a development model using the git version control system: new features are coded in the contributor branches first and merged to the QGIS master (the main branch) when they are finished and stable.

QGIS source code is hosted at https://github.com/qgis/QGIS.

3.1.1. Roles

Il existe différents rôles sur GitHub. Lorsque vous avez un compte sur GitHub, vous êtes déjà autorisé à contribuer en forkant le dépôt et vous avez le rôle de “contributeur”. Les développeurs principaux sont des “collaborateurs” et peuvent fusionner des branches dans le dépôt amont et officiel.

3.1.2. Environment

To get started using and contributing to the QGIS repository, you need to:

  1. have a GitHub account

  2. make your own copy of the QGIS repository (see fork)

  3. have a git client installed on your system

  4. set up your git environment

  5. and have fun!

3.1.3. Installing git

The git project provides recent versions of the software for most platforms. Follow the instructions at https://git-scm.com/downloads to get and install the copy corresponding to your OS and architecture. There, it’s also possible to install a git GUI client to browse and manage your repositories (most of the time, it will install git if not yet available).

3.2. Le développement par branches

3.2.1. Contributions au développement

Once signed up on GitHub and having forked the repository, you can engage as a contributor.

Note

Contributions to QGIS code can be done from your forked repository on the GitHub website. The new code will automatically be built by the test environment. But this workflow can quickly reveal its limits when you want to provide complex changes. Instructions below will assume a local clone.

You can contribute by initiating a pull request. To do that follow these generic steps:

  1. Clone your repository onto your local computer and set up the build environment

  2. Créer une nouvelle branche et faire les modifications pour le développement

  3. Validez vos modifications et repoussez votre branche vers le fork distant sur GitHub. Une demande amélioration est alors proposée comme lien web (URL) juste après .

  4. Ouvrez une demande d’amélioration (PR) demandant de transférer le(s) commit(s) de votre branche vers la branche master dans le dépôt amont.

  5. Un processus de révision est en cours pour informer les autres contributeurs et collaborateurs de votre demande amélioration. Vous devez être réactif à leurs commentaires et suggestions.

Note

Un flux de travail Fork & Pull de Github plus détaillé est disponible à l’adresse https://reflectoring.io/github-fork-and-pull/.

Note

Most of the QGIS projects (website, documentation, pyQGIS API, plugins…) are available in the project GitHub page and can get contributions, following the same process.

3.2.2. Accéder au Répertoire

To be able to interact from your local disk with both your remote fork and the QGIS upstream repositories, you need to:

  1. Make a clone of your copy on your local disk

    cd path/to/store/the/repository
    git clone https://github.com/<yourName>/QGIS.git
    
  2. Connect the QGIS main repository (we will name it upstream) to yours

    git remote add upstream https://github.com/qgis/QGIS.git
    
  3. Check connected remote repositories

    git remote -v
    # origin   https://github.com/<YourName>/QGIS.git (fetch)
    # origin   https://github.com/<YourName>/QGIS.git (push)
    # upstream https://github.com/qgis/QGIS.git (fetch)
    # upstream https://github.com/qgis/QGIS.git (push)
    

    Your online repository is now accessible from your local drive and you can interact with it using the name origin. Whenever you’d like to fetch changes from the qgis/QGIS repository, use upstream.

Note

In QGIS we keep our most stable code in the current release branch. master branch contains code for the so called “unstable” release series. Periodically we will branch a release off master, and then continue stabilisation and selective incorporation of new features into master.

See the INSTALL file in the source tree for specific instructions on building development versions.

3.2.3. Procédure

  1. Initial announcement on mailing list or issues repo:

    Before starting, make an announcement on the developer mailing list to see if another developer is already working on the same feature. You can also mention your interest as a comment in the issue report if one exists in the repo. If the new feature requires any changes to the QGIS architecture, a QGIS Enhancement Proposal (QEP) is needed.

  2. Create a branch in your local repository:

    Create a new git branch for the development of the new feature, based on latest state of the master branch.

    git fetch upstream master
    git checkout -b newfeature upstream/master
    
  3. Now you can start developing:

    Code your changes in your local disk with your usual IDE. Remember to write tests suite for your modifications, when appropriate.

  4. Commit your changes to the git repo:

    When making a commit, put a descriptive comment and rather do several small commits if the changes across a number of files are unrelated. Conversely we prefer you to group related changes into a single commit.

    git add path/to/your/files
    git commit -m "Add a comment describing your nice feature"
    
  5. Now, you may want to share your work with QGIS community members. Push your new feature up to your online fork repository by doing:

    git push origin newfeature
    

    Note

    If the branch already exists, your changes will be pushed into it, otherwise, it is created.

  6. Submit your changes with a pull-request

    With opening the pull-request, the automated test suite is triggered and checks whether your changes follow the coding guidelines of QGIS and do not break any existing feature. You’d need to fix any reported issues before your branch is merged upstream.

    Astuce

    We use GitHub actions to manage the tests to be run on the repository. For convenience, you can enable the actions on your repository so that the tests are run when you push the changes. You’d then open the pull request after they all passed, making the review process more efficient.

  7. Rebase to upstream master regularly:

    It is recommended to rebase to incorporate the changes in master to the branch on a regular basis. This makes it easier to merge the branch back to master later. After a rebase you need to git push -f to your forked repo.

    git pull --rebase upstream master
    git push -f origin newfeature
    

Note

Consultez les sites suivants pour plus d’information sur Git.

3.2.4. Tester avant de fusionner avec la branche master

Lorsque vous avez terminé avec la nouvelle fonctionnalité et êtes satisfait de sa stabilité, faites une annonce sur la liste des développeurs. Avant la fusion, les modifications seront testées par les développeurs et les utilisateurs.

3.3. Submitting Pull Requests

Il y a quelques règles qui vous aideront à obtenir vos correctifs et à extraire facilement les demandes dans QGIS, et à nous aider à traiter les correctifs envoyés plus facilement.

En général, passer par des pull requests via GitHub est beaucoup plus préférable pour les développeurs. Nous ne décrivons pas les pull requests ici, mais nous vous référons plutôt à sa documentation dans GitHub.

Si vous procédez via une pull request, nous vous remercions de bien vouloir vous assurer régulièrement que votre branche est à jour avec la branche master du projet, afin d’en faciliter l’intégration à tout moment.

Si vous êtes un développeur et que vous souhaitez évaluer la file des pull requests en attente de révision, il existe un outil simple qui vous permet de le faire en ligne de commande

In general when you submit a PR you should take the responsibility to follow it through to completion - respond to queries posted by other developers, seek out a “champion” for your feature and give them a gentle reminder occasionally if you see that your PR is not being acted on. Please bear in mind that the QGIS project is driven by volunteer effort and people may not be able to attend to your PR instantaneously. We do scan the incoming pull requests but sometimes we miss things. Don’t be offended or alarmed. Try to identify a developer to help you and contact them asking them if they can look at your patch. If you feel the PR is not receiving the attention it deserves your options to accelerate it should be (in order of priority):

  • Help review others pull requests to free the person assigned to yours.

  • Envoyez un message à la liste de diffusion à propos de votre PR pour nous dire combien il est important qu’elle puisse être intégrée au code principal.

  • Envoyer un message à la personne à qui est attribuée la PR dans la liste.

  • Envoyer un message à Marco Hugentobler (qui gère la file d’attente des PR)

  • Envoyez un message au comité de direction du projet en leur demandant assistance pour incorporer votre PR au code principal.

3.3.1. Bonnes pratiques pour la création de pull request

  • Commencez toujours une nouvelle branche pour une fonctionnalité à partir de la branche master actuelle.

  • Si vous codez une branche de fonctionnalité, ne « fusionnez » rien dans cette branche, plutôt rebasez comme décrit au point suivant pour garder votre historique propre.

  • Before you create a pull request do git fetch upstream and git rebase upstream/master (given upstream is the remote for qgis user and not your own remote, check your .git/config or do git remote -v | grep github.com/qgis).

  • Vous pouvez faire un git rebase comme dans la ligne précédente de manière répétée sans dommage (du moment que l’objectif de votre branche est d’être fusionnée dans la branche master).

  • Attention, après une opération de rebasement, vous devrez faire un git push -f vers votre dépôt forké. DÉVELOPPEURS PRINCIPAUX: NE FAITES PAS CELA DANS LE DEPÔT QGIS PUBLIC !

3.3.2. Notifications destinées à la documentation

There is a special label (Needs Documentation) that can be assigned by reviewers to your pull request to automatically generate issue reports in QGIS-Documentation repository as soon as your pull request is merged. Remember to mention whether your feature deserves such a label.

Moreover, you can add special tags to your commit messages to provide more information to documenters. The commit message is then added to the generated issue report:

  • [needs-docs] permet aux rédacteurs d’identifier des correctifs ou des améliorations apportées à une fonctionnalité déjà existante.

  • [feature] pour une nouvelle fonctionnalité. Fournir une bonne description dans la PR est vivement recommandé.

Les développeurs sont donc priés de bien vouloir ajouter ces tags (insensibles à la casse) afin de faciliter la gestion des tickets pour la documentation mais aussi pour l’aperçu global des modifications liées à la version. Mais, veuillez s’il vous plaît prendre le temps d’ajouter quelques commentaires: soit dans le commit, soit dans la documentation elle-même.

3.3.3. Vérifications nécessaires

QGIS est sous licence GPL. Vous devez vous assurer que vous soumettez des patchs non encombrés de problème de propriété intellectuelle. Ne soumettez pas de code non disponible sous licence GPL.

3.4. Obtenir les droits d’écriture dans Git

L’accès en écriture à l’arbre des sources QGIS se fait par invitation. Généralement, lorsqu’une personne soumet plusieurs patchs conséquents (sans nombre fixe de participation) qui démontre de solides compétences et compréhension du C++ et des conventions de code QGIS, un des membres du PSC ou d’autres développeurs QGIS peuvent proposer au PSC de lui fournir les droits d’écriture. La personne qui recommande le nouveau venu doit rédiger un paragraphe promotionnel pour expliquer pourquoi il pense que la personne citée doit obtenir les droits d’écriture. Dans certains cas, nous donnerons accès à des développeurs non C++ comme des traducteurs et des personnes en charge de la documentation. Dans ce cas, la personne doit avoir fait la preuve de son habileté à proposer des patchs et devrait avoir soumis plusieurs patchs démontrant sa compréhension de la modification de la base de code, de manière propre, sans rien casser, etc.

Note

Depuis le passage à Git, nous sommes moins enclins à fournir des droits en écriture aux nouveaux développeurs car il est maintenant trivial de partager du code sous GitHub en forkant QGIS et en proposant des pull requests.

Merci de vérifier que tout se compile correctement avant de créer des commits ou des pull requests. Essayez de rester attentif aux possibles problèmes que vos commits peuvent générer pour les développeurs compilant sur d’autres plateformes ou avec des versions plus ou moins récentes des différentes bibliothèques.