Une contribution étape par étape

Note

Bien que la documentation de QGIS est utilisée pour expliquer le processus, toutes les commandes et étapes montrées en-dessous sont également applicables au site web de QGIS.

Maintenant que vous connaissez sur le bout des doigts les règles à suivre pour rédiger une documentation réussie de QGIS, voyons plus concrètement les étapes pour rédiger la documentation et comment vous pouvez simplement et rapidement partager vos modifications avec la communauté.

En supposant que vous avez déjà un compte GitHub, il vous faudra d’abord cloner les fichiers sources de la documentation afin d’avoir votre propre copie de travail: allez à la page du dépôt QGIS-Documentation (par commodité, ce dépôt sera nommé qgis/QGIS-Documentation dans la suite du document) et cliquez sur le bouton Fork dans l’angle supérieur droit.

Quelques secondes plus tard, un dépôt QGIS-Documentation est ajouté dans votre compte GitHub (https://github.com/<VotreNom>/QGIS-Documentation). Ce dépôt est une copie dans laquelle vous avez un droit d’écriture total et vous pourrez y effectuier toute sorte de modifications sans craindre d’affecter la documentation officielle. Au départ, ce dépôt contient les mêmes branches que le dépôt qgis/QGIS-Documentation et est par défaut sur la branche master. Les branches sont des lignes de développement parallèles pouvant contenir différentes versions de la doc, qui peuvent être fusionnées ou diverger. Créez de préférence une branche pour chaque ticket que vous souhaitez traiter. Et sachez que vous pouvez créer autant de branches que vous voulez.

Astuce

Effectuez vos modifications dans une branche ad’hoc, jamais dans la branche master

Par convention, évitez de faire des changements dans votre branche master à part merger les modifications de la branche master de qgis/QGIS-Documentation (nommée qgis:master). Utilisez cette dernière comme modèle pour créer de nouvelles branches afin de vous assurer un historique de branche propre et sain.

Il y a différentes façons de contribuer à la documentation QGIS. Bien que nous les exposions ci-dessous séparément, elles ne sont pas mutuellement exclusives, ce qui signifie que vous pouvez, à n’importe quel moment, passer d’un processus à l’autre sans risque, car elles suivent toutes le schéma suivant :

  1. Effectuez vos modifications dans une branche ad’hoc de votre dépôt

  2. Publier vos changements et demander à fusionner à la documentation principale à travers un pull request (PR)

  3. Les autres vérifient, discutent d’éventuelles améliorations et intègrent votre travail dans la branche principale dès lors que tout semble ok.

Utiliser l’interface web de GitHub

Depuis vos répertoires clonés, vous pouvez maintenant proposer les changements vers la documentation principale. En effet, l’interface web de GitHub vous offre des moyens de le faire facilement:

  • Modifier vos fichiers, pré-visualiser et envoyer vos changements

  • Créer une pull request pour ajouter vos modifications dans le répertoire principal.

  • Créer, mettre à jour ou supprimer des branches

Lire le projet GitHub Hello-world pour apprendre les bases du vocabulaire et des actions qui seront utilisées ci-dessous.

Faire des changements dans votre répertoire

La documentation peut être améliorée en adressant les problèmes rencontrés en parcourant la documentation sous https://github.com/qgis/QGIS-Documentation/issues. Elles peuvent être de différentes sortes : faute de frappe, manquement de fonctionnalité, description erronée ou dépassée...

Alternative 1 : Prendre une issue dans la liste

  1. Sélectionner l’issue que vous voulez résoudre. Pour éviter que plusieurs personnes s’attaquent à la même issue, vous pouvez informer les contributeurs de votre choix en ajoutant un commentaire à l’issue report et obtenir l’assignation pour cette dernière.

  2. Depuis votre répertoire, créer (et se déplacer dans) une branche au nom vous aidant à vous rappeler de quoi il s’agit.

  3. Parcourir les fichiers sources jusqu’au fichier à modifier.

  4. Basculer le fichier en mode Edition en utilisant l’icône “crayon” et procéder à vos modifications en suivant le guide guidelines.

  5. Validez vos changement en remplissant le cadre Commit Changes et effectuez le “commit” directement vers votre branche.

  6. Répétez les étapes précédentes pour tout autre fichier qui nécessiterait d’être mis à jour afin de corriger le problème.

Alternative 2: Utiliser le raccourci Fix Me

Le projet QGIS dispose d’un moyen simple d’atteindre un fichier source depuis la documentation en ligne. En effet, au lieu de parcourir tous les fichiers source dans GitHub pour trouver celui en lien avec le problème, ou si vous trouvez une erreur en lisant les manuels, vous n’avez qu’à cliquer sur le lien “Fix Me” en bas de la page pour ouvrir son fichier source en mode Edition.

  1. Ceci ouvrira le fichier dans la branche “qgis:master” avec un message en haut de la page vous informant que vous n’avez pas d’accès en écriture sur ce dépôt et que vos modifications seront appliquées dans une nouvelle branche de votre dépôt.

  2. Procédez à vos modifications en suivant les lignes directrices disponibles à l’adresse http://docs.qgis.org/testing/en/docs/documentation_guidelines/

  3. Dès que vous avez terminé, en bas de la page, commentez brièvement sur quoi portent vos modifications et cliquez sur Propose File change. Ceci va générer une nouvelle branche (patch-xxx) dans votre dépôt.

Astuce

Si votre branche master est la même que qgis:master, vous pouvez remplacer sans risque qgis par <YourName> dans le lien. Dans ce cas, une fois que vos changements sont faits, vous devez choisir radioButtonOn Create a new branch for this commit and start a pull request et vous n’aurez pas à vous préoccuper de modifier master.

Partager vos changements via un Pull Request

Maintenant, vous disposez d’une nouvelle branche dans QGIS avec un fichier qui diverge de qgis:master. Pour intégrer vos changements dans la documentation officielle, vous avez besoin de réaliser une “pull request”.

  1. En fait, après avoir “commité” vos changements, GitHub ouvre une nouvelle page pour la comparaison des branches:

    • Si vous avez utilisé Fix Me sans changer l’url, la comparaison se fait entre votre branche patch-xxx et qgis:master (la ramification de base est la branche master sur``qgis/QGIS-Documentation``).

    • Si vous avez utilisé une branche que vous aviez nommée vous même alors la comparaison s’effectue entre cette branche et votre branche master personnelle (la base est tout simplement master). Par conséquent, il vous faut quitter cette page et passer à l’étape suivante.

  2. Dans tous les cas (y compris lorsque vous envoyez une branche vers GitHub en ligne de commande) vous pouvez créér une nouvelle “pull request” à n’importe quel moment depuis beaucoup de pages. Il suffit d’aller sur la page principale du dépôt (le vôtre ou celui de qgis), cliquez sur New Pull Request et Comparer les branches (si nécessaire). Assurez vous d’avoir sélectionné qgis/QGIS-Documentation avec master comme branche de base et que la branchede tête est votre dépôt <YourName>/QGIS-Documentation contenant votre branche modifiée.

    Astuce

    Bien qu’elle ait été publiée et traduite, la documentation de QGIS 2.14 est toujours maintenue et les problèmes signalés font l’objet de corrections. Si vous voulez corriger des problèmes dans la documentation de la version courante, remplacez la branche master par la branche manual_fr_... appropriée dans les étapes précédentes.

  3. Une coche verte à côté des branches comparées signifie que vos modifications peuvent être fusionnée automatiquement dans la documentation officielle. Cliquez sur le bouton Create pull request. Une croix rouge signifie que les fichiers que vous modifiez ne sont pas à jour par rapport à la branche cible (une contribution y a été ajoutée depuis la création ou la dernière mise à jour de votre branche). Il faut alors utiliser git command line tools pour corriger le problème.

  4. Remplissez le formulaire si nécessaire et cliquez à nouveau sur Create pull request .

  5. Une nouvelle PR est ajoutée à https://github.com/qgis/QGIS-Documentation/pulls et n’importe qui peut la voir et la commenter.

  6. Cela va déclencher une Compilation Travis CI et vérifier automatiquement si votre contribution ne contient aucune erreur de compilation. Si une erreur est détectée, une croix rouge apparaît à côté de votre contribution. Il suffit de cliquer dessus ou sur Details dans le résumé en bas de la page pour avoir les précisions sur l’erreur. Vous devez corriger toutes les erreurs ou les avertissements avant que vos modifications soient enregistrées dans le dépôt.

  7. Jusqu’à ce que votre PR soit fusionné avec le dépôt principal, vous avez la possibilité d’ajouter des modifications à votre proposition. Dans les faits, toute nouvelle modification de votre branche est ajoutée à votre “pull request”. Utilisez cette possibilité si la modification est en rapport avec le problème que vous corrigez, dans le cas contraire, créez une nouvelle branche pour ces modifications en utilisant la procédure décrite précédemment.

  8. Lorsque tout vous semble correct, un “commiter” peut fusionner votre banche avec le dépôt principal. Votre contribution est validée.

  9. Si vous le souhaitez, vous pouvez désormais supprimer la branche que vous utilisiez, ceci afin d’éviter d’avoir trop de branches (inutilisées ou désuets) qui polluent votre dépôt.

Réaliser ces petites étapes vont vous permettre d’apprendre plus facilement la manière de faire.

Warning

Soyez attentif à lancer vos pull request sur qgis:master et non sur votre propre branche master, faute de quoi personne ne sera informé de vos changements et vous pourriez par erreur fusionner vos changements dans votre branche master, ce qui polluerait son historique.

Astuce

Fermeture automatique d’un rapport d’erreur dans une pull request

Pour faciliter la gestion des rapports d’erreurs, indiquez le numéro de l’erreur que vous adressez dans votre pull-request. Pour faire ceci, utilisez l’instruction #issue_number. Si elle est précédée de termes comme fix, close... l’erreur concernée sera fermée dès que la pull request est fusionnée.

Utiliser les outils de ligne de commande Git

Si l’interface web de GitHub vous aide à mettre à jour le dépôt avec votre contribution d’une façon simple, elle ne dispose pas d’outils pour :

  • regrouper vos commits et nettoyer votre historique des modifications

  • fixe les conflits avec le dépôt principal si nécessaire...

  • construire la documentation pour tester vos modifications

Ensuite, vous aurez besoin de ‘install git <https://git-scm.com/downloads>`_ sur votre disque dur pour accéder à des outils encore plus avancés et puissants, mais aussi pour obtenir une copie local du dépôt. Quelques bases dont vous aurez besoin le plus souvent sont expliquées ci dessous. Vous trouverez également les règles à suivre même si vous optez pour l’interface web.

Dans les exemples de code ci dessous, les lignes commençant par $ représente les commandes que vous aurez à taper, alors que les # sont des commentaires.

Dépôt local

Maintenant, vous êtes prêt à récupérer un clone local de votre dépôt QGIS-Documentation

$ cd ~/Documents/Development/QGIS/
$ git clone git@github.com:<YourName>/QGIS-Documentation.git

La ligne de commande précédente n’est qu’un exemple. Il faut adapter le chemin et l’URL du dépôt en remplaçant “<YourName>” par votre nom d’utilisateur.

Astuce

Permission denied (publickey) error?

Si vous avez un message “Permission denied (publickey) error”, il pourrait y avoir un problème avec votre clé SSH. Consultez GitHub help pour plus de précisions.

Vérifier le :

$ git remote -v
origin  git@github.com:<YourName>/QGIS-Documentation.git (fetch)
origin  git@github.com:<YourName>/QGIS-Documentation.git (push)
$ git branch
* master

  • origin est le nom du dépôt distant de votre dépôt QGIS-Documentation.

  • master est la branche principale par défaut. Vous ne devriez jamais l’utiliser pour vos contributions ! Jamais!

Vous pouvez commencez à travailler d’ici, mais à la longue, vous aurez beaucoup d’erreurs lorsque vous voudrez soumettre vos contributions (appelées Pull Request dans la procédure de GitHub) étant donné que la branche principale du dépôt QGIS-Documentation divergera de votre dépôt local/distant.

Ajoutez un autre dépôt distant

Pour pouvoir suivre l’avancement du travail réalisé sur le projet principal, ajoutez un nouveau dépôt distant dans votre dépôt local. Ce nouveau dépôt distant sera le dépôt QGIS-Documentation du projet QGIS :

$ git remote add upstream git@github.com:qgis/QGIS-Documentation.git
$ git remote -v
origin  git@github.com:<YourName>/QGIS-Documentation.git (fetch)
origin  git@github.com:<YourName>/QGIS-Documentation.git (push)
upstream        git@github.com:qgis/QGIS-Documentation.git (fetch)
upstream        git@github.com:qgis/QGIS-Documentation.git (push)

Désormais, vous avez le choix entre deux dépôts distants :

  • origin pour “pousser” votre branche locale dans votre dépôt distant

  • upstream pour fusionner (si vous avez les droits pour le faire) votre contribution avec le dépôt officiel OU pour mettre à jour votre branche “master” sur le dépôt local à partir de la branche “master” du dépôt officiel.

Note

upstream est juste un intitulé, une sorte de nom standard, mais vous pouvez l’appeler comme vous voulez.

Mettez à jour votre branche de base

Pour la documentation testing (branche master)

Avant de travailler sur une nouvelle contribution, vous devez toujours mettre à jour votre branche locale master dans votre dépôt local. Lancez simplement cette commande :

# switch to master branch (it is easy to forget this step!)
$ git checkout master
# get "information" from the master branch in upstream repository
# (aka qgis/QGIS-Documentation's repository)
$ git fetch upstream master
# merge update from upstream/master to the current local branch
# (which should be master, see step 1)
$ git merge upstream/master
# update **your** remote repository
$ git push origin master

Vous disposez maintenant d’un dépôt local et d’un dépôt distant qui ont tous deux une branche master à jour par rapport à QGIS-Documentation de l’organisation QGIS. Vous pouvez commencer à travailler sur votre contribution.

Pour la documentation publiée (branche manual_en_)

En parallèle de la documentation de la version en test, nous continuons à corriger les problèmes dans la documentation de QGIS 2.14, ce qui veut dire que vous pouvez aussi y contribuer. En vous inspirant de la section précédente, vous pouvez facilement le faire en sélectionnant la branche correspondante.

Lorsque vous dupliquez le dépôt (voir Dépôt local), votre copie contient toutes les branches du dépôt père. Comme plus haut, vous devez vous assurer que votre branche est à jours avec les banches du dépôt père:

# change branch e.g. for 2.14 LTR
$ git checkout manual_en_2.14
# get "information" from the manual_en_2.14 branch in upstream repository
$ git fetch upstream manual_en_2.14
# merge update from upstream/manual_en_2.14 to the current local branch
$ git merge upstream/manual_en_2.14
# update **your** remote repository
$ git push origin manual_en_2.14

De cette façon vos branches locale et distante pour la version 2.14 sont à jour par rapport à la branche du dépôt père officiel.

Contribuez dans votre branche de production

Maintenant que la branche de base est mise à jour, il vous faut créer une branche spéciale pour accueillir vos modifications. Ayez le réflexe de toujours travailler sur une branche autre que celle de base - souvent la master! Toujours!

$ git checkout -b myNewBranch
# checkout means go to the branch
# and -b flag creates a new branch if needed, based on current branch
$ git branch
master
manual_en_2.14
* myNewBranch
# a list of existing branch where * means the current branch
# You can now add your contribution, by editing the concerned file
# with any application (in this case, vim is used)
$ vim myFile
# once done
$ git add myFile
$ git commit

Quelques remarques à propos des commandes de commit/push :

  • essayez de ne “commiter” qu’une seule contribution (changement atomique). En d’autres termes, n’adressez qu’une seule erreur à la fois.

  • essayez d’expliquer avec soin ce que vous avez modifié dans le titre de votre commit et dans la description. La première ligne est un titre, doit commencer par une lettre majuscule, devra contenir 80 caractères au maximum et ne devra pas se terminer par un .. Soyez concis. Votre description peut être plus longue et se termine par un .. Vous pouvez y donner plus de détails.

  • utilisez un # avec un nombre pour faire référence à un problème. Préfixez avec Fix si vous fixez le ticket: votre commit fermera le ticket.

Maintenant que vos modifications sont sauvegardées et intégrées dans votre branche locale, il va falloir les envoyer sur le dépôt en ligne, afin de pouvoir créer des pull-requests:

$ git push origin myNewBranch

Partagez vos modifications

Vous pouvez maintenant aller dans votre dépôt github et create a Pull Request comme expliqué dans une section précédente. Assurez-vous de créer un PR depuis votre branche vers la branche distante cible dans le dépôt officiel de QGIS-Documentation.

Nettoyez votre dépôt local et distant.

Une fois que votre PR a été fusionnée dans le QGIS-Documentation officiel, vous pouvez supprimer votre branche. En effet, si vous contribuez souvent, vous vous retrouverez d’ici quelques semaines avec un nombre considérable de branches inutilisées. Du coup, gardez votre dépôt propre de cette façon :

# delete local branch
$ git branch -d myNewBranch
# Remove your remote myNewBranch by pushing nothing to it
$ git push origin :myNewBranch

Et n’oubliez pas de mettre à jour la branche master dans votre dépôt local!