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. à l’aide de l’interface web de Github

  2. avec des outils de ligne de commande Git.

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 githubFork 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

Pages on the QGIS documentation website can be edited quickly and easily by clicking on the Edit on GitHub link at the top right of each page.

  1. Cela ouvrira le fichier dans la branche qgis:master avec 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.

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

  3. When you finish, make a short comment about your changes and click on Propose changes. This will generate a new branch (patch-xxx) in your repository.

  4. After you click on Propose changes, github will navigate to the Comparing changes page.

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

      1. Accédez à votre fork de documentation QGIS (https://github.com/<YourName>/QGIS-Documentation)

      2. Cliquez sur githubBranch et recherchez la branche patch-xxx. Sélectionnez cette branche de patch. Le bouton githubBranch va maintenant dire Branch: patch-xxx

      3. Descendez à Modify files 1 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 githubBranch 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 githubBranch 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

  1. Parcourez les fichiers source de votre fork de QGIS-Documentation jusqu’au fichier à modifier

  2. Procédez à vos modifications en suivant les règles d’écriture.

  3. 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é.

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

../../_images/githubCompareAcrossForks.png

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.

../../_images/githubCreatePullRequestComparison.png

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 githubCantMerge

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

Though being translated, the latest version of QGIS documentation is still maintained and existing issues are fixed. If you are fixing issues for a different release, change base from master to the appropriate release_... branch in the steps above.

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 :

  1. Accédez à la page des demandes d’amélioration et cliquez sur la demande d’amélioration que vous souhaitez commenter.

  2. Au bas de la page, vous trouverez une zone de texte où vous pouvez laisser des commentaires généraux sur la demande amelioration.

  3. Pour ajouter des commentaires sur des lignes spécifiques,

    1. Cliquez sur githubFilesChanged et recherchez le fichier que vous souhaitez commenter. Vous devrez peut-être cliquer sur Afficher le diff source pour voir les changements.

    2. Faites défiler jusqu’à la ligne que vous souhaitez commenter et cliquez sur githubBluePlus. 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.

  • or as part of a review, pressing the Start a review button. Your comments are not automatically sent after validation, allowing you to edit or cancel them afterwards, to add a summary of the main points of the review or global instructions regarding the pull request and whether you approve it or not. This is the convenient way since it’s more flexible and allows you to structure your review, edit the comments, publish when you are ready and send a single notification to the repository followers and not one notification for each comment. Get more details.

../../_images/githubAddLineComment.png

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

  1. Basculez vers onglet githubFilesChanged

  2. Appuyez sur Ajouter une suggestion au lot pour chaque reformulation que vous souhaitez inclure. Vous verrez un compteur augmenter au fur et à mesure.

  3. 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 githubFilesChanged dans votre page de demande d’amélioration et cliquez sur le bouton crayon githubEditPencil à 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.

  1. Navigate to your fork of the QGIS-Documentation repository (https://github.com/<YourName>/QGIS-Documentation).

  2. Click on the Branches tab. Below Your branches you’ll see a list of your branches.

  3. Click on the deleteSelected Delete this branch icon to delete any unwanted branches.

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 [email protected]:<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  [email protected]:<YourName>/QGIS-Documentation.git (fetch)
origin  [email protected]:<YourName>/QGIS-Documentation.git (push)
$ git branch
* master

You can start to work here but in the long term process you will get a lot of issues when you will push your contribution (called Pull Request in github process) as the master branch of the qgis/QGIS-Documentation repository will diverge from your local/remote repository. You then need to keep track of the main remote repository and work with 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 [email protected]:qgis/QGIS-Documentation.git
$ git remote -v
origin  [email protected]:<YourName>/QGIS-Documentation.git (fetch)
origin  [email protected]:<YourName>/QGIS-Documentation.git (push)
upstream        [email protected]:qgis/QGIS-Documentation.git (fetch)
upstream        [email protected]: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é

Along with the testing documentation, we continue to fix issues in the latest release, meaning that you can also contribute to it. Follow the previous section sample code, replacing master with the corresponding branch of the latest 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 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

1.2.5. Partagez vos modifications

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

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:

  • 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/