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.

Installation

Installation de git pour GNU/Linux

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

sudo apt-get install git

Installation de git sous MS-Windows

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

Installation de git sous OSX

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 le source de git depuis http://git-scm.com/. Dézippez l’archive et dans un terminal, rendez vous dans le répertoire des sources 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 (IHM), vous pouvez les désactiver avant de lancer make avec:

export NO_PERL=
export NO_TCLTK=
export NO_PYTHON=

Accès au dépôt

Pour cloner le dépôt QGIS, branche master:

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

Basculer vers une branche

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 master:

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.

Sources de la documentation QGIS

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 readme qui est inclus dans le dépôt de la documentation pour plus d’information.

Sources du site web QGIS

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 readme qui est inclus dans le dépôt du site web pour plus d’information.

Documentation Git

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

Développement par branches

Objectif

La complexité du code source QGIS a considérablement augmenté au cours des dernières années. Ainsi, il est difficile d’anticiper les effets colatéraux de l’ajout d’une fonctionnalité. Dans le passé, le projet QGIS avait de longs cycles de publication car il y avait beaucoup de travail de stabilisation après ajout de nouvelles fonctionnalités. Pour régler ces problèmes, QGIS a basculé vers un modèle de développement ou les nouvelles fonctionnalités sont codées d’abord dans des branches Git, puis fusionnées vers la branche master (la branche principale) lorsque leur implémentation est terminée et stable. Ce chapitre décrit la procédure de création de branche et de fusion au sein du projet QGIS.

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éez une branche: créez une nouvelle branche Git pour le développement de la nouvelle fonctionnalité.

git checkout -b newfeature

Vous pouvez maintenant commencer le développemenlt. 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à, vos changements seront poussés dedans.

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 origin! Ne l’utilisez que dans votre propre branche de production.

git rebase master

Documentation sur le Wiki

Il est également recommandé de documenter les changements prévus ainsi que l’état de développement sur une page du Wiki.

Tests avant la fusion vers la branche master

Lorsque vous avez terminé la nouvelle fonctionnalité et que l’état de stabilité est satisfaisant, faites une annonce sur la liste de diffusion des développeurs. Avant de fusionner, les changements doivent être testés par les développeurs et les utilisateurs.

Soumettre des patchs et des pull-requests

Il existe quelques guides qui vous aideront à insérer vos patchs et vos pull-requests dans QGIS et qui nous aideront à injecter les patchs reçus plus facilement.

Pull Requests

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.

Si vous êtes un développeur et que vous voulez évaluer la file de pull request, il existe un outil simple qui vous permettra 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 elle est important qu’elle puisse être intégrée au code principal.
  • Envoyez un message à la personne à qui votre PR a été assignée dans la file des PR.
  • Envoyez un message à Marco Hugentobler (qui gère la file des PR).
  • Envoyez un message au comité de direction du projet en leur demandant assistance pour incorporer votre PR dans la base de code.

Bonnes pratiques pour la création de pull request

  • Démarrez toujours une branche pour votre fonctionnalité depuis la branche courante.
  • 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 !

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

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
  • Optionnellement: 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)

Nom des fichiers de patch

Si le patch est une correction pour un bogue donné, merci de nommer le fichier an ajoutant le numéro de bogue, ex: bug777fix.patch et d’ajouter ce fichier au rapport de bogue 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 trac et d’y attacher le patch.

Créez votre patch dans la racine du répertoire des sources QGIS

Cela permet d’appliquer le patch plus facilement étant donné que nous n’auront 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.

Faire en sorte que votre patch soit remarqué

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

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.

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 (comme 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.