Une contribution é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.

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.

For any help, do not hesitate to either ask in a comment on the issue report you are trying to fix or write to the QGIS-community-team list. More details at Get involved in documentation.

Let’s now dive into the process.

Documentation sources are stored using the git version control system and are available on GitHub at https://github.com/qgis/QGIS-Documentation. There are two main ways, not mutually exclusive, to modify the files:

  1. Using the GitHub web interface

  2. Using Git command line tools.

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

If you are not yet familiar with git and GitHub vocabulary, you may want to read the GitHub Hello-world project to learn some basic vocabulary and actions that will be used below.

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

In your GitHub account you will find a QGIS-Documentation repository (https://github.com/<YourName>/QGIS-Documentation). This repository is a copy of the official QGIS-Documentation repository where you have full write access and you can make changes without affecting the official documentation.

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 raccourci Corrigez-moi

Les pages sur le site QGIS peuvent être éditées rapidement et facilement en cliquant sur le lien Corrigez-moi situé en bas de page.

  1. This will open the file in the qgis:master branch with a message at the top of the page telling you that you don’t have write access to this repo and your changes will be applied to a new branch of your repository.

  2. Do your changes. Since the documentation is written using the reStructureText syntax, depending on your changes, you may need to rely on the writing guidelines.

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

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

    • If you’re done making changes, skip to Compare changes in the Share your changes via Pull Request section below.

    • S’il y a des changements supplémentaires à effectuer avant de les soumettre à QGIS, suivez ces étapes :

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

      2. Click on githubBranch and search for the patch-xxx branch. Select this patch branch. The githubBranch button will now say Branch: patch-xxx

      3. Jump down to Modify files below.

Alternative 2 : Créer une branche ad hoc dans votre dépôt de documentation

You can edit files directly from your fork of the QGIS Documentation.

Click on githubBranch 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 githubBranch button should now say Branch: branch_name

Astuce

Do your changes in an ad hoc branch, never in the master branch

By convention, avoid making changes in your master branch except when you merge the modifications from the master branch of qgis/QGIS-Documentation into your copy of the QGIS-Documentation repository. Separate branches allow you to work on multiple problems at the same time without interfering with other branches. If you make a mistake you can always delete a branch and start over by creating a new one from the master branch.

3. Modifier des fichiers

  1. Browse the source files of your fork of QGIS-Documentation to the file that needs to be modified

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

  3. When you finish, navigate to the Commit Changes frame at the bottom of the page, make a short comment about your changes, and click on Commit Changes to commit the changes directly to your branch. Make sure Commit directly to the branch_name branch. is selected.

  4. Repeat the previous steps for any other file that needs to be updated to fix the issue

Partager les changements via un Pull Request

Vous devez effectuer une pull request pour ajouter vos modifications dans la documentation officiel.

Note

Si vous avez utilisé le lien Corrigez-moi

After you commit your changes GitHub will automatically open a new page comparing the changes you made in your patch-xxx branch to the qgis/QGIS-Documentation master branch.

Skip to Step 2 below.

1. Start a new pull request

Navigate to the main page of the QGIS-Documentation repository and click on New pull request.

2. Compare changes

If you see two dialog boxes, one that says base:master and the other compare:branch_name (see figure), this will only merge your changes from one of your branches to your master branch. To fix this click on the compare across forks link.

../../_images/githubCompareAcrossForks.png

If your Comparing changes page looks like this, click on the compare across forks link.

You should see four drop-down menus. These will allow you to compare the changes that you have made in your branch with the master branch that you want to merge into. They are:

  • base fork: the fork that you want to merge your changes into

  • base: the branch of the base fork that you want to merge your changes into

  • head fork: the fork that has changes that you want to incorporate into the base fork

  • compare: the branch with those changes

Select qgis/QGIS-Documentation as the base fork with master as base, set the head fork to your repository <YourName>/QGIS-Documentation, and set compare to your modified branch.

../../_images/githubCreatePullRequestComparison.png

Comparing changes between qgis/QGIS-Documentation and your repository

A green check with the words Able to merge shows that your changes can be merged into the official documentation without conflicts.

Click the Create pull request button.

Avertissement

Si vous voyez githubCantMerge

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

Though released and being translated, the documentation of QGIS 3.4 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.

3. Describe your pull request

A text box will open: fill in any relevant comments for the issue you are addressing.

If this relates to a particular issue, add the issue number to your comments. This is done by entering # and the issue number (e.g. #1234). If preceded by terms like fix or close, the concerned issue will be closed as soon as the pull request is merged.

Add links to any documentation pages that you are changing.

Click on Create pull request

4. Make corrections

A new pull request will automatically be added to the Pull requests list. Other editors and administrators will review your pull request and they may make suggestions or ask for corrections.

A pull request will also trigger a Travis CI build which automatically checks your contribution for build errors. If Travis CI finds an error, a red cross will appear next to your commit. Click on the red cross or on Details in the summary section at the bottom of the pull request page to see the details of the error. You’ll have to fix any reported errors or warnings before your changes are committed to the qgis/QGIS-Documentation repository.

You can make modifications to your pull request until it is merged with the main repository, either to improve your request, to address requested modifications, or to fix a build error.

To make changes click on the githubFilesChanged tab in your pull request page and click the pencil button githubEditPencil next to the filename that you want to modify.

Any additional changes will be automatically added to your pull request if you make those changes to the same branch that you submitted in your pull request. For this reason, you should only make additional changes if those changes relate to the issue that you intend to fix with that pull request.

If you want to fix another issue, create a new branch for those changes and repeat the steps above.

An administrator will merge your contribution after any build errors are corrected, and after you and the administrators are satisfied with your changes.

5. Review and comment pull request

You can make comments on the changes in a pull request. Navigate to the pull request page and click on the pull request that you want to comment on.

At the bottom of the page you will find a text box where you can leave general comments about a pull request.

To add comments about specific lines, click on githubFilesChanged and find the file you want to comment on. You may have to click on Load diff to see the changes. Scroll to the line you want to comment on and click on the githubBluePlus. That will open a text box allowing you to leave a comment.

5. Delete your merged branch

You can delete the branch after your changes have been merged. Deleting old branches saves you from having unused and outdated branches in your repository.

Navigate to your fork of the QGIS-Documentation repository (https://github.com/<YourName>/QGIS-Documentation). Click on the Branches tab. Below Your branches you’ll see a list of your branches. Click on the deleteSelected Delete this branch icon to delete any unwanted branches.

Utiliser les outils de ligne de commande Git

The GitHub web interface is an easy way to update the QGIS-documentation repo with your contributions, but it doesn’t offer tools to:

  • group your commits and clean your change history

  • fix possible conflicts with the main repo

  • construire la documentation pour tester vos modifications

You need to install git on your hard drive in order to get access to more advanced and powerful tools and have a local copy of the repository. Some basics you may often need are exposed below. You’ll also find rules to care about even if you opt for the web interface.

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

Now you are ready to get a local clone of your QGIS-Documentation repository.

You can clone your QGIS repository using the web URL as follows:

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

Check the following:

# 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!

Alternatively you can clone your QGIS repository using the SSH protocol:

# 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?

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.

Check the following if you used the SSH protocol:

# 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

You can start to work here but in the long terme process you will get a lot of issue when you will push your contribution (called Pull Request in github process) as the master branch of the 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.

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)

Similarly, you can use the SSH protocol to add a remote repository in your local repository:

$ 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

Before working on a new contribution, you should always update your master branch in your local repository. Assuming you are willing to push changes to the testing documentation, run the following command lines:

# 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

Now you have your local and remote repositories which both have their master branch up to date with the official master branch of QGIS-Documentation. You can start to work on your contribution.

Note

Switch the branch if you wish to contribute to released doc

Along with the testing documentation, we continue to fix issues in QGIS 3.4 doc, meaning that you can also contribute to it. Follow the previous section sample code, replacing master with the corresponding branch of the latest documentation.

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

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!

Further reading

  • Other than the Github web interface and the git command line tools exposed above, there are also GUI applications you can use to create and manage your contributions to the documentation.