1. Contribuer étape par étape¶
Note
Bien que la documentation de QGIS soit utilisée pour expliquer le processus, toutes les commandes et étapes montrées en-dessous sont également applicables au site web de QGIS (dans le dépôt QGIS-Website).
Si vous lisez ces lignes, c’est sûrement parce que vous souhaitez contribuer à écrire la documentation de QGIS et cherchez un guide pratique. Vous êtes au bon endroit! Ce document vous guidera à travers les différentes façons d’atteindre cet objectif, vous indiquant les étapes principales, les astuces que vous pouvez utiliser et les pièges dont vous devez vous méfier.
Pour toute aide, n’hésitez pas à demander dans un commentaire sur le rapport de problème que vous essayez de corriger ou à écrire dans la liste QGIS-community-team. Plus de détails sur Participez à la documentation.
Plongeons-nous maintenant dans le processus.
Les sources de documentation sont stockées à l’aide du système de contrôle de version git et sont disponibles sur GitHub à l’adresse https://github.com/qgis/QGIS-Documentation. Il existe deux façons principales, non mutuellement exclusives, de modifier les fichiers:
1.1. Utiliser l’interface web de GitHub¶
L’interface web de GitHub vous permet de faire comme suit:
éditer des fichiers
prévisualiser et valider vos changements
Créer une pull request pour ajouter vos modifications dans le répertoire principal.
Créer, mettre à jour ou supprimer des branches
Si vous n’êtes pas encore familier avec le vocabulaire git et GitHub, vous pouvez lire le projet Hello-world de Github pour apprendre un vocabulaire de base et les actions qui seront utilisées ci-dessous.
Note
Si vous corrigez un problème signalé
Si vous comptez apporter des corrections à un signalement, ajoutez un commentaire au rapport d’erreur afin de vous le faire assigner. Ceci empêchera que plus d’une personne travaille sur la même erreur.
1.1.1. 1. « Forker » QGIS-Documentation¶
Dans l’hypothèse où vous avez déjà un compte GitHub, il vous faudra d’abord cloner les fichiers source de la documentation.
Naviguez vers la page QGIS-Documentation repository et cliquez sur le bouton 
en haut à droite.
Dans votre compte GitHub, vous trouverez un dépôt pour la documentation QGIS (https://github.com/<YourName>/QGIS-Documentation). Ce dépôt est une copie du dépôt QGIS-Documentation officiel où vous avez un accès complet en écriture et vous pouvez apporter des modifications sans affecter la documentation officielle.
1.1.2. 2. Faire des changements¶
Il y a différentes façons de contribuer à la documentation QGIS. Bien que nous les exposions ci-dessous séparément, vous pouvez passer d’un processus à l’autre sans risque.
1.1.2.1. Alternative 1: Utiliser le lien Edit on GitHub¶
Chaque page de la documentation QGIS peut être modifiée rapidement et facilement en cliquant sur le lien Edit on GitHub en haut à droite de celle-ci.
Cela ouvrira le fichier dans la branche
qgis:masteravec un message en haut de la page vous indiquant que vous n’avez pas accès en écriture à ce dépôt et vos modifications seront appliquées à une nouvelle branche de votre dépôt.Faites vos changements. Étant donné que la documentation est écrite à l’aide de la syntaxe reStructureText, en fonction de vos modifications, vous devrez peut-être vous baser sur les Recommandations pour la documentation.
Lorsque vous avez terminé, faites un bref commentaire sur vos modifications et cliquez sur Propose changes. Cela va générer une nouvelle branche (
patch-xxx) dans votre dépôt.Après avoir cliqué sur Propose changes github accède à la page Comparing changes (Comparaison des modifications).
Si vous avez terminé d’apporter des modifications, passez à Partagez vos modifications dans la section Partager les changements via une Pull Request ci-dessous.
S’il y a des changements supplémentaires à effectuer avant de les soumettre à QGIS, suivez ces étapes :
Accédez à votre fork de documentation QGIS (
https://github.com/<YourName>/QGIS-Documentation)Cliquez sur
et recherchez la branche patch-xxx. Sélectionnez cette branche de patch. Le bouton va maintenant dire Branch: patch-xxxPassez à la section Modifier des fichiers ci-dessous.
Note
Le lien Edit on GitHub est aussi accessible depuis le menu déroulant au bas de la barre verticale à gauche de chaque page.
1.1.2.2. Alternative 2 : Créer une branche ad hoc dans votre dépôt de documentation¶
Vous pouvez modifier des fichiers directement à partir de votre fork de la documentation QGIS.
Cliquez sur dans le coin supérieur gauche de votre dépôt QGIS-Documentation forké et entrez un nom unique dans le champ de texte pour créer une nouvelle branche. Le nom de la nouvelle branche doit être lié au problème que vous souhaitez résoudre. Le bouton devrait maintenant indiquer Branch: nom_branche
Astuce
Faites vos changements dans une branche ad hoc, jamais dans la branche **``master``
Par convention, évitez de faire des changements dans votre branche master sauf lorsque vous fusionnez les modifications de la branche master de qgis/QGIS-Documentation dans votre copie du dépôt QGIS-Documentation. Des branches distinctes vous permettent de travailler sur plusieurs problèmes en même temps sans interférer avec d’autres branches. Si vous faites une erreur, vous pouvez toujours supprimer une branche et recommencer en en créant une nouvelle à partir de la branche principale.
1.1.3. 3. Modifier des fichiers¶
Parcourez les fichiers source de votre fork de QGIS-Documentation jusqu’au fichier à modifier
Procédez à vos modifications en suivant les règles d’écriture.
Lorsque vous avez terminé, accédez au cadre Valider les modifications au bas de la page, faites un bref commentaire sur vos modifications et cliquez sur : guilabel:Valider les modifications pour valider les modifications directement dans votre branche. Assurez-vous que Valider directement dans la branche nom_branche. est sélectionné.
Répétez les étapes précédentes pour tout autre fichier qui doit être mis à jour pour résoudre le problème
1.1.4. Partager les changements via une Pull Request¶
Vous devez effectuer une pull request pour ajouter vos modifications dans la documentation officiel.
Note
Si vous avez utilisé un lien Edit on GitHub
Après avoir validé vos modifications, GitHub ouvrira automatiquement une nouvelle page comparant les modifications que vous avez apportées dans votre branche patch-xxx à la branche principale qgis/QGIS-Documentation.
Passez à l”Étape 2 ci-dessous.
1.1.4.1. 1. Lancer une nouvelle demande d’amelioration¶
Accédez à la page principale de QGIS-Documentation <https://github.com/qgis/QGIS-Documentation> _ repository et cliquez sur nouvelle demande amélioration.
1.1.4.2. 2. Comparer les modifications¶
Si vous voyez deux boîtes de dialogue, l’une qui dit base:master et l’autre compare:nom_branche (voir figure), cela ne fera que fusionner vos modifications d’une de vos branches vers votre branche principale. Pour résoudre ce problème, cliquez sur le lien Comparer à travers les branches.
Fig. 1.1 Si votre page Comparaison des modifications ressemble à ceci, cliquez sur le lien comparaison entre les branches.¶
Vous devriez voir quatre menus déroulants. Ceux-ci vous permettront de comparer les modifications que vous avez apportées dans votre branche avec la branche principale dans laquelle vous souhaitez fusionner. Elles sont:
banche base: la branche dans laquelle vous souhaitez fusionner vos modifications
base: la branche de la fourche de base dans laquelle vous souhaitez fusionner vos modifications
branche de tête: la fourche qui a des changements que vous souhaitez intégrer dans la branche de base
comparer: la branche avec ces changements
Sélectionnez qgis/QGIS-Documentation comme branche de base avec master comme base, définissez la fourche de tête sur votre dépôt <YourName>/QGIS-Documentation, et comparer à votre branche modifiée.
Fig. 1.2 Comparaison des modifications entre qgis/QGIS-Documentation et votre dépôt¶
Une coche verte avec les mots Capable de fusionner montre que vos modifications peuvent être fusionnées dans la documentation officielle sans conflits.
Cliquez sur le bouton Créer une demande amélioration.
Avertissement
Si vous voyez 
Cela signifie qu’il existe des conflits <https://help.github.com/articles/addressing-merge-conflicts/> _. Les fichiers que vous modifiez ne sont pas à jour avec la branche que vous ciblez, car quelqu’un d’autre a effectué une validation qui entre en conflit avec vos modifications. Vous pouvez toujours créer la demande d’extraction, mais vous devrez corriger tout conflit pour terminer la fusion.
Astuce
Bien qu’en cours de traduction, la documentation de la dernière version de QGIS est toujours maintenu et les problèmes existants sont résolus. Si vous résolvez des problèmes pour une version différente, remplacez base de master par la branche release_... appropriée dans les étapes ci-dessus.
1.1.4.3. 3. Décrivez votre demande d’amélioration.¶
Une zone de texte s’ouvrira: remplissez les commentaires pertinents pour le problème que vous abordez.
Si cela concerne un problème particulier, ajoutez le numéro du problème à vos commentaires. Pour ce faire, saisissez # et le numéro du problème (par exemple #1234). S’il est précédé de termes tels que fix ou close, le signalement concerné sera clos dès que la pull request sera fusionnée.
Ajoutez des liens vers toutes les pages de documentation que vous modifiez.
Cliquez sur Créer une demande d’amélioration.
1.1.4.4. 4. Examinez et commentez la demande d’amelioration¶
Comme vu ci-dessus, n’importe qui peut soumettre des modifications à la documentation par le biais de pull requests. De même, n’importe qui peut examiner les demandes d’amélioration avec des questions et des commentaires. Peut-être que le style d’écriture ne correspond pas aux directives du projet, qu’il manque certains détails majeurs ou captures d’écran au changement, ou peut-être que tout a l’air bien et est en ordre. La révision permet d’améliorer la qualité de la contribution, tant sur le fond que sur la forme.
Pour examiner une demande amelioration :
Accédez à la page des demandes d’amélioration et cliquez sur la demande d’amélioration que vous souhaitez commenter.
Au bas de la page, vous trouverez une zone de texte où vous pouvez laisser des commentaires généraux sur la demande amelioration.
Pour ajouter des commentaires sur des lignes spécifiques,
Cliquez sur
et recherchez le fichier que vous souhaitez commenter. Vous devrez peut-être cliquer sur Afficher le diff source pour voir les changements.Faites défiler jusqu’à la ligne que vous souhaitez commenter et cliquez sur
. Cela ouvrira une zone de texte vous permettant de laisser un commentaire.
Des commentaires de ligne spécifiques peuvent être publiés:
sous forme de commentaires simples, en utilisant le bouton Ajouter un seul commentaire. Ils sont publiés au fur et à mesure. N’utilisez ceci que si vous avez peu de commentaires à ajouter ou lorsque vous répondez à un autre commentaire.
ou dans le cadre d’une révision, en appuyant sur le bouton Start a review. Vos commentaires ne sont pas envoyés automatiquement après validation, ce qui vous permet de les modifier ou de les annuler par la suite, d’ajouter un résumé des principaux points de la révision ou des instructions globales concernant la demande d’amélioration et si vous l’approuvez ou non. Ce moyen est le plus pratique car il est plus flexible et vous permet de structurer votre avis, de modifier les commentaires, de publier lorsque vous êtes prêt et d’envoyer une seule notification aux abonnés du dépôt et pas une notification pour chaque commentaire. Obtenez plus de détails.
Fig. 1.3 Commenter une ligne avec une suggestion de changement¶
Les commentaires de ligne peuvent incorporer des suggestions que le rédacteur de demande d’amelioration peut appliquer à la demande d’amelioration. Pour ajouter une suggestion, cliquez sur le bouton 
Insérer une suggestion en haut de la zone de texte du commentaire et modifiez le texte dans le bloc de suggestion.
Astuce
Préférez la validation des suggestions à votre demande amelioration par lots
En tant qu’auteur de demande d’amélioration, lorsque vous intégrez directement les commentaires des réviseurs dans votre demande d’amélioration, évitez d’utiliser le bouton Commit suggestion en bas du commentaire lorsque vous avez de nombreuses suggestions à traiter et préférez les ajouter en tant que commit batch, C’est:
Basculez vers onglet
Appuyez sur Ajouter une suggestion au lot pour chaque reformulation que vous souhaitez inclure. Vous verrez un compteur augmenter au fur et à mesure.
Appuyez sur l’un des boutons Valider les suggestions lorsque vous êtes prêt à appliquer les suggestions à votre demande d’amelioration, puis entrez un message décrivant les modifications.
Cela ajoutera toutes les modifications à votre branche en tant que validation unique, résultant en un historique des modifications plus lisible et moins de notifications pour les abonnés du référentiel. Soit dit en passant, procéder comme cela vous permettra également d’économiser de nombreux clics.
1.1.4.5. 5. Apportez des corrections¶
Une nouvelle demande d’amélioration sera automatiquement ajoutée à la Liste des suggestions d’amélioration. D’autres éditeurs et administrateurs examineront votre proposition d’amélioration et pourront faire des suggestions ou demander des corrections.
Une demande d’amélioration déclenchera également une test Travis CI qui vérifie automatiquement votre contribution pour les erreurs de construction. Si Travis CI trouve une erreur, une croix rouge apparaîtra à côté de votre commit. Cliquez sur la croix rouge ou sur Détails dans la section récapitulative au bas de la page de demande d’amélioration pour voir les détails de l’erreur. Vous devrez corriger toutes les erreurs ou avertissements signalés avant que vos modifications ne soient validées dans le dépôt qgis/QGIS-Documentation.
Vous pouvez apporter des modifications à votre demande d’extraction jusqu’à ce qu’elle soit fusionnée avec le dépôt principal, soit pour améliorer votre demande, pour répondre aux modifications demandées, soit pour corriger une erreur de génération.
Pour apporter des modifications, cliquez sur l’onglet dans votre page de demande d’amélioration et cliquez sur le bouton crayon 
à côté du nom de fichier que vous souhaitez modifier.
Toute modification supplémentaire sera automatiquement ajoutée à votre demande d’amelioration si vous apportez ces modifications à la même branche que celle que vous avez soumise dans votre demande d’amélioration. Pour cette raison, vous ne devez apporter des modifications supplémentaires que si ces modifications sont liées au problème que vous avez l’intention de résoudre avec cette demande d’amelioration
Si vous souhaitez résoudre un autre problème, créez une nouvelle branche pour ces modifications et répétez les étapes ci-dessus.
Un administrateur fusionnera votre contribution une fois que toutes les erreurs de génération auront été corrigées et que vous et les administrateurs serez satisfaits de vos modifications.
1.1.5. 5. Supprimez votre branche fusionnée¶
Vous pouvez supprimer la branche une fois vos modifications fusionnées. La suppression d’anciennes branches vous évite d’avoir des branches inutilisées et obsolètes dans votre dépôt.
Accédez à votre fork du dépôt de la documentation de QGIS (
https://github.com/<YourName>/QGIS-Documentation).Cliquez sur l’onglet Branches. Dans Your branches, vous verrez une liste de vos branches.
Cliquez sur le bouton
Delete this branch pour supprimer les branches non désirée.
1.2. Utiliser les outils de ligne de commande Git¶
L’interface Web GitHub est un moyen facile de mettre à jour le dépôt de documentation QGIS avec vos contributions, mais elle ne propose pas d’outils pour :
regroupez vos commits et nettoyez votre historique des changements
résoudre les conflits possibles avec le dépôt principal
construire la documentation pour tester vos modifications
Vous devez installer git sur votre disque dur afin d’avoir accès à des outils plus avancés et plus puissants et avoir une copie locale du dépôt. Certaines notions de base dont vous aurez souvent besoin sont exposées ci-dessous. Vous trouverez également des règles à respecter 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.
1.2.1. Dépôt local¶
Vous êtes maintenant prêt à obtenir un clone local de votre dépôt de documentation QGIS.
Vous pouvez cloner votre dépôt QGIS à l’aide de l’URL Web comme suit :
# move to the folder in which you intend to store the local repository
$ cd ~/Documents/Development/QGIS/
$ git clone https://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.
Vérifiez les points suivants :
# Enter the local repository
$ cd ./QGIS-Documentation
$ git remote -v
origin https://github.com/<YourName>/QGIS-Documentation.git (fetch)
origin https://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 également cloner votre dépôt QGIS à l’aide du protocole SSH :
# move to the folder in which you intend to store the local repository
$ cd ~/Documents/Development/QGIS/
$ git clone git@github.com:<YourName>/QGIS-Documentation.git
Astuce
Permission denied (publickey) error?
Si vous obtenez une erreur Autorisation refusée (publickey) avec l’ancienne commande, il peut y avoir un problème avec votre clé SSH. Voir Aide GitHub pour plus de détails.
Vérifiez les points suivants si vous avez utilisé le protocole SSH:
# Enter the local repository
$ cd ./QGIS-Documentation
$ git remote -v
origin git@github.com:<YourName>/QGIS-Documentation.git (fetch)
origin git@github.com:<YourName>/QGIS-Documentation.git (push)
$ git branch
* master
Vous pouvez commencer à travailler ici, mais à long terme, vous obtiendrez beaucoup de problèmes lorsque vous pousserez votre contribution (appelée Pull Request dans le processus github) car la branche principale du dépôt qgis/QGIS-Documentation divergera de votre dépôt local / distant. Vous devez ensuite suivre le dépôt distant principal et travailler avec les branches.
1.2.2. 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 https://github.com/qgis/QGIS-Documentation.git
$ git remote -v
origin https://github.com/<YourName>/QGIS-Documentation.git (fetch)
origin https://github.com/<YourName>/QGIS-Documentation.git (push)
upstream https://github.com/qgis/QGIS-Documentation.git (fetch)
upstream https://github.com/qgis/QGIS-Documentation.git (push)
De même, vous pouvez utiliser le protocole SSH pour ajouter un dépôt distant dans votre dépôt local :
$ 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.
1.2.3. Mettez à jour votre branche de base¶
Avant de travailler sur une nouvelle contribution, vous devez toujours mettre à jour votre branche principale dans votre dépôt local. En supposant que vous souhaitiez apporter des modifications à la documentation de test, exécutez les lignes de commande suivantes :
# switch to master branch (it is easy to forget this step!)
$ git checkout master
# get "information" from the master branch in the 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 (aka <YourName>/QGIS-Documentation)
$ git push origin master
Vous avez maintenant vos dépôt locaux et distants qui ont tous deux leur branche master à jour avec la branche master officielle de la documentation QGIS. Vous pouvez commencer à travailler sur votre contribution.
Note
Changez de branche si vous souhaitez contribuer au document publié
En parallèle de la documentation de test, nous continuons à résoudre les problèmes de la dernière version, ce qui signifie que vous pouvez également y contribuer. Suivez l’exemple de code de la section précédente, en remplaçant master par la branche correspondante de la dernière documentation.
1.2.4. 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!
# Create a new branch
$ git checkout -b myNewBranch
# checkout means go to the branch
# and -b flag creates a new branch if needed, based on current branch
# Let's check the list of existing branches (* indicates the current branch)
$ git branch
master
release_2.18
...
* myNewBranch
# You can now add your contribution, by editing the concerned file(s)
# 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 avecFixsi 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
1.2.6. Nettoyez votre dépôt local et distant.¶
Une fois que votre PR a été fusionnée dans le dépôt officiel QGIS-Documentation, 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!
1.3. Pour aller plus loin¶
Outre l’interface Web Github et les outils de ligne de commande git exposés ci-dessus, il existe également des applications GUI que vous pouvez utiliser pour créer et gérer vos contributions à la documentation.
Lorsque les modifications de la demande d’extraction sont en conflit avec des modifications récentes transmises à la branche cible, les conflits doivent être résolus avant qu’une fusion ne soit possible:
si le conflit concerne quelques lignes concurrentes, un bouton Résoudre les conflits est disponible dans la page de demande d’extraction Github. Appuyez sur le bouton et résolvez le problème comme expliqué sur https://help.github.com/articles/resolving-a-merge-conflict-on-github/
si le conflit implique le renommage ou la suppression de fichiers, vous devrez résoudre le conflit à l’aide des lignes de commande git. En règle générale, vous devez d’abord rebaser votre branche sur la branche cible à l’aide de l’appel
git rebase targetBranchet corriger les conflits signalés. En savoir plus sur https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/
Parfois, à la fin du processus de relecture, vous pouvez vous retrouver avec des modifications divisées en plusieurs validations qui n’en valent pas nécessairement la peine. Les lignes de commande Git vous aident à écraser ces validations en un nombre plus petit et en des messages de validation plus significatifs. Quelques détails sur https://help.github.com/articles/using-git-rebase-on-the-command-line/