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.
Les utilisateurs d’une distribution Debian ou dérivée peuvent faire:
sudo apt-get install git
Windows users can obtain msys git or use git distributed with cygwin.
The git project has a downloadable build of git. Make sure to get the package matching your processor (x86_64 most likely, only the first Intel Macs need the i386 package).
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.
Download the source from http://git-scm.com/. Unzip it, and in a Terminal cd to the source folder, then:
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=
Clôner la branche ‘master’ de QGIS :
git clone git://github.com/qgis/QGIS.git
Pour basculer vers une branche (checkout), par exemple la branche de la version 2.6.1, faites:
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.
Si vous voulez vérifier les sources de la documentation QGIS:
git clone [email protected]: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.
Si vous voulez vérifier les sources du site web de QGIS:
git clone [email protected]: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.
Consultez les sites suivants pour plus d’information sur Git.
La complexité du code source de QGIS s’est considérablement accrue ces dernières années. Dès lors, il est difficile d’anticiper les effets de bord induits par l’ajout de fonctionnalités. Dans le passé, le projet QGIS avait de très long cycle de publication du fait du lourd travail à effectuer pour rétablir la stabilité du logiciel après l’ajout de nouvelles fonctionnalités. Pour dépasser ce problème, QGIS a basculé sur un modèle de développement où les nouvelles fonctionnalités sont d’abord programmées dans des branches GIT, puis fusionnées avec la branche principale (‘master’) lorsqu’elles sont finalisées et stables. Cette section décrit la procédure pour créer et fusionner des branches dans le projet QGIS.
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
It is also recommended to document the intended changes and the current status of the work on a wiki page.
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.
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.
Il est en général plus facile pour les développeurs que vous soumettiez des pull requests GitHub. Nous ne décrirons pas le mécanisme de pull requests ici mais vous pouvez vous référer à la documentation GitHub sur les pull requests.
Si vous avez créé une pull request, nous vous demandons de faire régulièrement une fusion de master vers la branche de votre PR de manière à ce que cette dernière puisse être toujours fusionnable directement avec la branche master.
If you are a developer and wish to evaluate the pull request queue, there is a very nice tool that lets you do this from the command line
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.
Commencez toujours une nouvelle branche pour une fonctionnalité à partir de la branche master actuelle.
Si vous développez une branche de nouvelle fonctionnalité, ne fusionnez rien dans cette branche. A la place, effectuez un rebasement (rebase) comme décrit dans le prochain point, de manière à conserver un 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 !
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] dans le cas où une nouvelle fonctionnalité est introduite. Fournir une bonne description de vos modifications est aussi vivement conseillé/apprécié.
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.
Option A:
cliquez sur le bouton merge (crée une fusion sans avance rapide)
Option B:
Test (également requis pour l’option A évidemment)
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)
If the patch is a fix for a specific bug, please name the file with the bug number in it e.g. bug777fix.patch, and attach it to the original bug report in trac.
If the bug is an enhancement or new feature, its usually a good idea to create a ticket in trac first and then attach your patch.
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.
QGIS developers are busy folk. We do scan the incoming patches on bug reports but sometimes we miss things. Don’t be offended or alarmed. Try to identify a developer to help you - using the Technical Resources and contact them asking them if they can look at your patch. If you don’t get any response, you can escalate your query to one of the Project Steering Committee members (contact details also available in the Technical Resources).
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.
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.