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 ci-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 dans Participer à la documentation.

Plongeons-nous maintenant dans le processus.

Les sources de la 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. Une liste de problèmes à résoudre et de fonctionnalités à expliquer est disponible à l’adresse https://github.com/qgis/QGIS-Documentation/issues.

Astuce

Si vous êtes un nouveau contributeur et que vous ne savez pas par où commencer, vous pouvez vous attaquer à nos rapports de bienvenue <https://github.com/qgis/QGIS-Documentation/issues?q=is%3Aissue+is%3Aopen+label%3AEasy>_.

Il y a 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. Fork 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. 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.

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.

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

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

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

     3. Passez à 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.

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.

First, make sure that your master branch is up to date with qgis:master branch. To do so:

1. Go to the main page of your repository, i.e. https://github.com/<YourName>/QGIS-Documentation. The master branch should be active with a mention whether it is up to date with qgis/QGIS-Documentation:master or not.

   If it has commits ahead the upstream branch, you better use the previous shortcut button alternative until you align your master branch.

   If it only has commits behind:

   1. Expand the Fetch Upstream drop-down menu on the right. You can

      • Compare the branches and see new changes in the main repository

      • Fetch and merge: takes changes from the upstream branch to yours.

   2. Let’s click Fetch and merge: after the process, your branch is mentioned as up to date with qgis/QGIS-Documentation:master.

2. Click on in the upper left corner of your forked QGIS-Documentation repository and enter a unique name in the text field to create a new branch . The name of the new branch should relate to the problem you intend to fix. The button should now say Branch: branch_name

3. You are ready to start new changes on top of it.

Attention

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. 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. Partagez vos modifications via les demandes d’amelioration

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.

Démarrer une nouvelle demande d’amélioration

Accédez à la page principale de QGIS-Documentation <https://github.com/qgis/QGIS-Documentation> _ repository et cliquez sur nouvelle demande amélioration.

Comparer les changements

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

This means that there are conflicts. The files that you are modifying are not up to date with the branch you are targeting because someone else has made a commit that conflicts with your changes. You can still create the pull request but you’ll need to fix any conflicts to complete the merge.

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.

Décrivez votre demande 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.

Examiner et commenter la demande d’amélioration

As seen above, anyone can submit modifications to the documentation through pull requests. Likewise anyone can review pull requests with questions and comments. Perhaps the writing style doesn’t match the project guidelines, the change is missing some major details or screenshots, or maybe everything looks great and is in order. Reviewing helps to improve the quality of the contribution, both in form and substance.

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

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:

1. Basculez vers onglet

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.

Faire 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 des vérifications automatiques de la construction (par exemple, pour le formatage des rst, les syntaxes du code python), et les rapports sont affichés en bas de la page. Si une erreur est trouvée, une croix rouge apparaîtra à côté de votre commit. Cliquez sur la croix rouge ou sur Détails dans la section résumé en bas de la page de la demande 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 référentiel 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. 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. Accédez à votre fork du dépôt de la documentation de QGIS (https://github.com/<YourName>/QGIS-Documentation).

2. Cliquez sur l’onglet Branches. Dans Your branches, vous verrez une liste de vos branches.

3. 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 première ligne de commande est simplement un exemple. Vous devez adapter à la fois le chemin et l’URL du dépôt, en remplaçant <YourName> par votre nom d’utilisateur github.

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?

If you get a Permission denied (publickey) error with the former command, there may be a problem with your SSH key. See GitHub help for details.

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

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 [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é

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

  • if the conflict relates to few competing lines, a Resolve conflicts button is available in the GitHub pull request page. Press the button and resolve the issue as explained at Resolving a merge conflict on GitHub

  • if the conflict involves files renaming or removal, then you’d need to resolve the conflict using git command lines. Typically, you have to first rebase your branch over the target branch using git rebase targetBranch call and fix the conflicts that are reported. Read more at Resolving a merge conflict using the command line

• Sometimes, at the end of the proofreading process, you may end up with changes split into multiple commits that are not necessarily worth it. Git command lines help you squash these commits to a smaller number and more meaningful commit messages. Some details at Using git rebase on the command line