3. Le processus de développement

Un projet basé sur git
Le développement par branches
Soumettre des pull requests
Obtenir les droits d’écriture dans Git

Comme c’est souvent le cas dans les projets open source, les contributions au code et à la documentation du projet sont très appréciées. La communauté QGIS est d’un grand soutien. Cette section décrit la procédure pour développer et fusionner vos contributions dans le projet QGIS.

3.1. Un projet basé sur git 

La complexité du code source de QGIS a considérablement augmenté au cours des dernières années. Par conséquent, il est difficile d’anticiper les effets secondaires à l’ajout d’une nouvelle fonctionnalité. Dans le passé, le projet QGIS avait de très longs cycles de publication, car il fallait beaucoup de travail pour rétablir la stabilité du système logiciel après l’ajout de nouvelles fonctionnalités. Pour surmonter ces problèmes, QGIS est passé à un modèle de développement utilisant le système de contrôle de version git <https://git-scm.com> où les nouvelles fonctionnalités sont d’abord codées dans les branches des contributeurs puis fusionnées pour devenir le master QGIS (la branche principale) lorsqu’elles sont terminées et stables.

Le code source de QGIS est hébergé à 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. Environnement 

Pour démarrer l’utilisation et la contribution au dépôt QGIS, il vous faut :

avoir un compte GitHub
réaliser sa propre copie du Dépôt QGIS (voir fork)
avoir installé un client git sur son système
régler son environnement git
et prendre plaisir!

3.1.3. Installer git 

Le projet git fournit des versions récentes du logiciel pour la plupart des plateformes. Suivez les instructions à l’adresse https://git-scm.com/downloads pour obtenir et installer la copie correspondant à votre système d’exploitation et à votre architecture. Il est également possible d’y installer un client GUI git pour parcourir et gérer vos dépôts (la plupart du temps, il installera git s’il n’est pas encore disponible).

3.2. Le développement par branches 

3.2.1. Contributions au développement 

Une fois inscrit sur GitHub et obtenu un dépôt dupliqué, vous pouvez vous engager en tant que contributeur.

Note

Les contributions au code de QGIS peuvent être effectuées à partir de votre branche dupliquée du dépôt sur le site de GitHub. Le nouveau code sera automatiquement construit par l’environnement de test. Mais ce fonctionnement peut rapidement révéler ses limites lorsque vous souhaitez apporter des modifications complexes. Les instructions ci-dessous supposeront une copie locale.

Vous pouvez contribuer en lançant une demande d’intégration. Pour ce faire, suivez ces étapes génériques :

Cloner votre dépôt sur votre ordinateur local et régler l’environnement de compilation
Créer une nouvelle branche et faire les modifications pour le développement
Valider vos modifications et proposer votre branche vers le dépôt distant sur GitHub. Une demande d’amélioration est alors proposée comme lien web (URL) juste après .
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.
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

La plupart des projets QGIS (site web, documentation, API pyQGIS, extensions …) sont disponibles dans la page projet GitHub et peuvent obtenir des contributions, en suivant le même processus.

3.2.2. Accéder au Répertoire 

Pour pouvoir interagir à partir de votre disque local avec votre duplication distante et les dépôts en amont de QGIS, vous devez :

Faites un clone de votre copie sur votre disque local.

cd path/to/store/the/repository
git clone https://github.com/<yourName>/QGIS.git

Connectez le dépôt principal de QGIS (nous lui donnerons le nom upstream) au vôtre.
```
git remote add upstream https://github.com/qgis/QGIS.git
```
Contrôler les dépôts distants connectés
```
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)
```
Votre dépôt en ligne est maintenant accessible depuis votre disque local et vous pouvez interagir avec lui en utilisant le nom origin. Si vous souhaitez récupérer les modifications du dépôt qgis/QGIS, utilisez upstream.

Note

Dans QGIS, nous conservons le code le plus stable dans la branche actuelle de la version publiée. La branche master contient le code pour la série de version appelée “non stable”. Périodiquement nous créons une version à publier depuis la branche master et nous continuons la stabilisation ainsi que l’incorporation sélective de nouvelles fonctionnalités dans la branche master.

Voir le fichier INSTALL dans l’arbre des sources pour des instructions spécifiques sur la construction des versions de développement.

3.2.3. Procédure 

Annonce initiale sur la liste de diffusion ou problèmes de dépôts:
Avant de commencer, faites une annonce sur la liste de diffusion développeur pour voir si un autre développeur travaille déjà sur la même fonctionnalité. Vous pouvez également mentionner votre intérêt dans un commentaire sur le rapport de problème s’il existe pour le dépôt. Si la nouvelle fonctionnalité nécessite des changements dans l’architecture de QGIS, une QGIS Enhancement Proposal (QEP) est nécessaire.
Créer une branche dans votre dépôt local :
Créer une nouvelle branche git basée sur le dernier état de la branche master pour le développement d’une nouvelle fonctionnalité.
git fetch upstream master git checkout -b newfeature upstream/master
Vous pouvez maintenant commencer à développer :
Coder vos modifications sur votre disque local avec votre IDE habituel. N’oubliez pas d’écrire une suite de tests pour vos modifications, le cas échéant.
Valider vos modifications dans le dépôt git :
Lorsque vous faites un commit, mettez un commentaire descriptif et faites plutôt plusieurs petits commits si les changements dans un certain nombre de fichiers ne sont pas liés. A l’inverse, nous préférons que vous regroupiez les changements liés en un seul commit.
git add path/to/your/files git commit -m "Add a comment describing your nice feature"
Maintenant, vous souhaitez peut-être partager votre travail avec les membres de la communauté QGIS. Mettez votre nouvelle fonctionnalité dans votre dépôt dupliqué en ligne en faisant :
```
git push origin newfeature
```
Note

Si la branche existe déjà, vos changements seront inclus dedans, sinon, elle sera créée.
:ref:`Soumettez vos modifications<submit_patch> ` avec une demande d’amélioration
En faisant la demande d’amélioration, la suite de tests automatisés est déclenchée et vérifie si vos modifications respectent les directives de codage de QGIS et ne cassent aucune fonctionnalité existante. Vous devrez corriger tout problème signalé avant que votre branche ne soit fusionnée en amont.

Astuce

Nous utilisons les actions GitHub pour gérer les tests à exécuter sur le dépôt. Pour plus de commodité, vous pouvez activer les actions sur votre dépôt afin que les tests soient exécutés lorsque vous faites les changements. Vous ouvrirez alors la demande d’amélioration après qu’ils soient tous effectués, rendant le processus de révision plus efficace.
Rebasez sur le master upstream régulièrement :
Il est recommandé de rebaser pour incorporer les changements à la branche master de façon régulière. Il sera plus facile de fusionner la branche vers le master. Après un rebasage, vous devez faire un git push -f sur votre dépôt dupliqué.
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. Soumettre des 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

En général, lorsque vous soumettez une demande d’amélioration, vous devez prendre la responsabilité de la suivre jusqu’à son terme : répondez aux questions posées par d’autres développeurs, cherchez un « champion » pour votre fonctionnalité et rappelez-lui gentiment de temps en temps si vous constatez que votre demande d’amélioration n’est pas prise en compte. N’oubliez pas que le projet QGIS est mené par des bénévoles et qu’il se peut que certaines personnes ne soient pas en mesure de s’occuper instantanément de votre demande d’amélioration. Nous parcourons les demandes d’amélioration entrantes, mais il nous arrive de manquer des choses. Ne soyez pas offensé ou alarmé. Essayez d’identifier un développeur pour vous aider et contactez-le pour lui demander s’il peut examiner votre correctif. Si vous estimez que votre demande d’amélioration ne reçoit pas l’attention qu’elle mérite, vous avez des options pour l’accélérer (par ordre de priorité) :

Participez à l’examen des demandes d’amélioration afin de libérer la personne affectée aux vôtres.
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 

Il existe une étiquette spéciale (Needs Documentation) qui peut être assignée par les réviseurs à votre demande d’amélioration pour générer automatiquement des rapports de problèmes dans le dépôt QGIS-Documentation dès que votre demande d’amélioration est fusionnée. N’oubliez pas de mentionner si votre fonctionnalité mérite une telle étiquette.

De plus, vous pouvez ajouter des balises spéciales à vos message de validation pour fournir plus d’informations aux documentalistes. Le message de validation est ensuite ajouté au rapport de problème :

[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.