3. Accès GIT¶

Ce chapitre décrit comment se lancer dans l’utilisation du dépôt GIT de QGIS. Avant de commencer, assurez-vous de disposer d’un client git installé sur votre système d’exploitation.

3.1. Installation ¶

3.1.1. Installation de git pour GNU/Linux ¶

Les utilisateurs d’une distribution Debian ou dérivée peuvent faire:

sudo apt install git

3.1.2. Installation de git sous Windows ¶

Les utilisateurs de MS Windows peuvent utiliser msys git ou utiliser le client git distribué avec cygwin.

3.1.3. Installation de git sous macOS ¶

Le projet git dispose d’un binaire téléchargeable de git. Assurez-vous de prendre le paquet conforme à votre processeur (x86_64 la plupart du temps, seuls les premiers Macs Intel utiliseront le paquet i386).

Une fois téléchargé, ouvrez l’image disque et lancez l’installeur.

Note pour l’architecture PPC/Source

Le site de git ne met pas à disposition des binaires pour PPC. Si vous en avez besoin ou si vous voulez plus de contrôle sur l’installation, vous devrez compiler git vous-même.

Téléchargez les sources depuis https://git-scm.com/. Décompressez-les dans un répertoire. Ouvrez un terminal pointant sur ce répertoire puis :

make prefix=/usr/local
sudo make prefix=/usr/local install

Si vous n’avez pas besoin des extensions, de Perl, de Python ou de TclTk (GUI), vous pouvez les désactiver avant de lancer make avec:

export NO_PERL=
export NO_TCLTK=
export NO_PYTHON=

3.2. Accéder au Répertoire ¶

Clôner la branche “master” de QGIS :

git clone git://github.com/qgis/QGIS.git

3.3. Basculer vers une branche ¶

Pour extraire une branche, par exemple la branche de la version 2.6.1, procédez comme suit:

cd QGIS
git fetch
git branch --track origin release-2_6_1
git checkout release-2_6_1

Pour basculer sur la branche maitre:

cd QGIS
git checkout master

Note

Dans QGIS, nous conservons le code le plus stable dans la branche 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 branche à publier depuis la branche master et non continuons la stabilisation ainsi que l’incorporation sélective de nouvelles fonctionnalités dans la branche master.

Consultez le fichier INSTALL dans l’arbre des sources pour plus d’instruction sur la compilation des versions de développement.

3.4. Sources de la documentation de QGIS ¶

Si vous voulez vérifier les sources de la documentation QGIS:

git clone git@github.com:qgis/QGIS-Documentation.git

Vous pouvez également jeter un oeil au fichier Lisez-moi qui est inclus dans le dépôt de la documentation pour plus d’information.

3.5. Sources du site web QGIS ¶

Si vous voulez vérifier les sources du site web de QGIS:

git clone git@github.com:qgis/QGIS-Website.git

Vous pouvez également jeter un oeil au fichier Lisez-moi qui est inclus dans le dépôt du site web pour plus d’information.

3.6. Documentation GIT ¶

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

3.7. Le développement par branches ¶

3.7.1. Objectif ¶

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 que l’ajout d’une fonctionnalité aura. 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 où les nouvelles fonctionnalités sont d’abord codées dans les branches GIT et fusionnées pour devenir master (la branche principale) lorsqu’elles sont terminées et stables. Cette section décrit la procédure de branchement et de fusion dans le projet QGIS.

3.7.2. Procédure ¶

Annonce initiale sur la liste de diffusion :
Avant de commencer, faites une annonce sur la liste de diffusion des développeurs pour voir si personne d’autre que vous ne travaille déjà sur la même fonctionnalité. Prenez également contact avec le conseiller technique du comité de direction du projet (PSC). Si la nouvelle fonctionnalité impose des changements d’architecture dans QGIS, un avis (RFC) est obligatoire.

Créer une branche : créer une nouvelle branche GIT pour le développement d’une nouvelle fonctionnalité.

git checkout -b newfeature

Vous pouvez maintenant commencer le développement. Si vous pensez travailler intensément sur cette branche et que vous voulez partager ce travail avec d’autres développeurs et avoir accès en écriture au dépôt amont, vous pouvez pousser votre dépôt dans le dépôt QGIS officiel par:

git push origin newfeature

Note

Si la branche existe déjà, les modifications seront ajoutées dans celle-ci.

Rebaser régulièrement vers la branche master: il est recommandé de réaliser un rebasage pour incorporer les changements de la branche master vers la branche courante, de manière régulière. Cela permet de faciliter la fusion ultérieure de la branche courante vers la branche master. Après un rebasage, vous devez lancer git push -f` dans votre dépôt dupliqué.

Note

Ne faites jamais git push -f sur le dépôt d’origine! Ne l’utilisez que dans votre propre branche de production.

git rebase master

3.7.3. 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.8. Envoi de correctifs et de demandes ¶

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.

3.8.1. Envoi des demandes ¶

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

Merci de consulter le chapitre ci-dessous sur comment “notifier votre patch”. En général, lorsque vous soumettez une PR, vous devrez prendre la responsabilité de la suivre au long de son intégration, en répondant aux questions posées par les autres développeurs, trouver un “champion” pour cette fonctionnalité et envoyer un courtois rappel si vous constatez que votre PR n’attire pas trop l’attention. Merci de garder à l’esprit que QGIS est un projet conduit par des volontaires et qu’il est probable que votre PR n’attire pas l’attention immédiatement. Si vous pensez que la PR ne reçoit pas l’attention qu’elle mérite, voici vos options pour accélérer son intégration (par ordre de priorité):

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.8.1.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.
Avant de créer une pull request, lancez git fetch origin et git rebase origin/master (origin étant ici le dépôt distant amont et non votre propre dépôt, vérifiez votre fichier .git/config ou faites: git remote -v | grep github.com/qgis pour identifier le nom utilisé dans votre configuration).
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.8.1.2. Notifications destinées à la documentation ¶

Outre les tags habituels pour classer votre PR, il existe des tags spéciaux permettant de générer automatiquement des tickets dans le dépôt de la documentation dès lors que votre PR est accepté.

[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.8.1.3. Pour fusionner une pull request ¶

Option A:

cliquez sur le bouton merge (crée une fusion sans avance rapide)

Option B:

Vérifiez une pull request
Test (également requis pour l’option A évidemment)
checkout master, git merge pr/1234
En option: git pull --rebase: Crée une avance rapide, aucun commit de fusion n’est réalisé. Meilleur historique mais il est plus difficile de revenir en arrière.
git push (NE JAMAIS utiliser l’option -f ici)

3.9. Nom des fichiers de patch ¶

Si le patch est une correction pour un bug donné, merci de nommer le fichier avec le numéro de bug dedans, ex: bug777fix.patch et d’ajouter ce fichier dans le rapport de bug originel.

Si le bogue est une amélioration ou une nouvelle fonctionnalité, il est généralement bon de créer d’abord un ticket dans GitHub et d’y attacher le patch.

3.10. Créez votre patch à la racine du répertoire des sources QGIS ¶

Cela permet d’appliquer le patch plus facilement étant donné que nous n’aurons pas besoin de naviguer dans un emplacement spécifique des sources. De plus, lorsque je reçois des patchs, je les inspecte en utilisant merge et avoir le patch à la racine du répertoire des sources est bien plus facile. Ci-dessous, voici un exemple pour inclure plusieurs changements de fichiers dans votre patch à partir de la racine des sources:

cd QGIS
git checkout master
git pull origin master
git checkout newfeature
git format-patch master --stdout > bug777fix.patch

Cela permettra de vous assurer que la branche master est synchronisée avec la branche du dépôt amont et cela générera un patch contenant le delta entre votre branche de nouvelle fonctionnalité et ce qui se trouve dans la branche master.

3.10.1. Faire en sorte que votre patch soit remarqué ¶

Les développeurs QGIS sont très occupés. Nous effectuons des recherches sur les patchs soumis dans les rapports de bug mais nous oublions parfois certaines choses. N’en prenez pas offense et ne vous alarmez pas. Essayez d’identifier les développeurs qui pourront vous aider et contactez-les pour leur demander de jeter un œil à votre patch. Si vous n’avez pas de réponse, vous pouvez remonter votre demande à l’un des membres du Comité de Direction du Projet (PSC, les détails de contacts sont également disponibles dans les Ressources Techniques).

3.10.2. 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.11. 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.

Lorsque vous faites un commit, votre éditeur de texte (défini dans la variable d’environnement $EDITOR) apparaîtra et vous devriez écrire un commentaire au début du fichier (au dessus de la partie qui indique “ne modifiez pas ceci”). Inscrivez un commentaire descriptif et faites plutôt plusieurs petits commits si vous effectuez des changements sur des fichiers qui ne sont pas liés entre eux. Inversement, nous préférerions que vous regroupiez les changements liés entre eux dans un seul commit.