Gerrit/Tutorial/fr

Ceci est un tutoriel qui explique comment utiliser Git et Gerrit pour les développements Wikimedia.


 * Si vous voulez gagner du temps et que vous êtes calés techniquement, utilisez à la place le guide simplifié Comment faire ? :
 * Pour les utilisateurs chevronnés, fournit d'autres documents supplémentaires.
 * si vous voulez juste essayer Gerrit et que vous ne voulez pas écrire un patch pour un projet logiciel Wikimedia réel, utilisez notre instance de test Gerrit à la place.

Dans ce tutoriel, les commandes à entrer commencent par un signe dollar '$' dans une boîte, comme ceci :. N'entrez pas le préfixe. Si une commande inclut aussi une variable que vous devez modifier personnellement, alors la variable s'affiche en rouge :.

Qu'est-ce que Git?
Git est un logiciel gratuit et ouvert de système distribué de contrôle des versions. Distribué signifie qu'il n'existe pas de copie centrale du dépôt. Avec Git, dès que vous avez cloné un dépôt, vous avez à votre disposition une copie complètement fonctionnelle de son code source, avec toutes ses branches et les versions labellisées.

Qu'est-ce que Gerrit?
Gerrit est un outil gratuit de relecture collaborative de code, basé sur le web et s'intégrant à Git.

Pour faire simple, vous soumettez vos propositions de modifications logicielles (dénommées usuellement patch, et changeset dans Gerrit) à l'intérieur d'une nouvelle branche. Si votre première version (patchset 1) n'est pas parfaite, vous pouvez la reprendre plusieurs fois même, pour la corriger (faire des amend) sur cette branche (patchset 2, etc). Dès que quelqu'un attribue un  au patchset suite à la relecture du code, celui-ci sera accepté et fusionné dans la branche principale du dépôt de code (habituellement appelée branche master). Fusionner signifie que vos modifications sont incluses par défaut à quiconque ouvrira ou téléchargera ce dépot logiciel.

Créer un compte Wikimedia développeur
Si vous n'avez pas encore de compte développeur Wikimedia ? créez-le sur wikitech.wikimedia.org. Le même nom d'utilisateur et le même mot de passe seront utilisés pour vous connecter à Gerrit ci-dessous.

Configurer Git
Ces instructions vous expliquent comment instaler Git comme outil en mode ligne de commande (fenêtre de terminal). Si vous préférez une interface utilisateur graphique (GUI) au lieu de la commande en ligne, cochez la liste des clients maintenus par le projet Git. Pour d'autres instructions d'installation voir la ldocumentation officielle.

Font Awesome 5 brands linux.svg Linux

 * Utiliser l'outil graphique de gestion des paquets logiciels de votre distribution Linux pour installer le paquet.
 * Si Git n'est pas fourni avec votre distribution, demandez le au forum du support de votre distribution.

Font Awesome 5 brands windows.svg Windows

 * Installer Git pour Windows à partir de https://gitforwindows.org/. Ceci fournit Git plus avec un environnement « Git Bash » accessible dans une fenêtre de commande permettant de faire fonctionner sous Windows, la plupart des commandes de ces instructions.

Apple logo black.svg macOS

 * Installez le gestionnaire de paquets Homebrew puis exécutez la commande – Ceci est recommandé car il permet une mise à jour simple et une installation facile des autres paquets.
 * Vous pouvez également installer via l'exécutable Git for Mac à la place.

Configurer Git
Maintenant que Git est installé, c'est le moment de configurer vos informations personnelles. Vous n'avez à faire ceci qu'une seule fois. Vous pouvez aussi à tout instant modifier vos informations personnelles en exécutant ces commandes à nouveau.

Git enregistre les utilisateurs qui font des validations (commit) en contrôlant le nom d'utilisateur et son adresse courriel. En plus, cette information est utilisée pour associér vos validations à votre compte Gerrit.

Entrez les deux commandes ci-dessous pour définir votre noms d'utilisateur et votre adresse courriel. Remplacez par votre propre nom d'utilisateur Gerrit, et  par votre propre adresse courriel :

Définir les clés SSH dans Gerrit
Nous utilisons une clé SSH pour établir une connexion sécurisée entre votre ordinateur et Gerrit. Pour savoir si vous avez à générer une nouvelle clé, il faut vérifier s'il n'en existe pas déjà une sur votre système. Exécutez cette commande dans une fenêtre de terminal :

La commande va lister les fichiers se trouvant dans le répertoire (caché). Si le répertoire existe déjà dans votre système et si la sortie liste un fichier qui s'appelle, alors vous pouvez sauter directement ici.

Générer une nouvelle clé SSH
Pour générer une nouvelle clé SSH, entrez la commande ci-dessous et remplacez par votre propre adresse courriel. Nous voulons la configuration par défaut, donc lorsqu'on nous demandera d'entrer le fichier contenant la clé enregistrée, pressez simplement la touche entrée.

Entrez une phrase de passe (passphrase) forte et unique et pressez la touche [Enter].


 * Pourquoi la phrase de passe est importante ?


 * Les mots de passe de sont pas très sûrs. If you use one that’s easy to remember, it’s easier to guess or brute-force. If you use one that’s random it’s hard to remember, so you might write the password down. Les deux sont très mauvais. C'est pourquoi vous utilisez les clés ssh. Mais utiliser une clé ssh sans phrase de passe c'est comme écrire ce mot de passe aléatoire dans un fichier de votre ordinateur. Quiconque aura accès à votre disque pourra accéder à tout système qui utilise cette clé. C'est pourquoi vous ajoutez également une phrase de passe. To not enter a long passphrase every time you use the key, there’s a tool called . Il peut garder votre phrase de passe en sécurité. If you use macOS or Linux, then your keys can be saved in the system’s keychain to make your life even easier.

La commande  va créer 2 fichiers dans le répertoire   :
 * : votre clé privée SSH (pour l'identification)
 * : votre clé publique SSH

Copier sa clé publique SSH
Récupérez le contenu du fichier de votre clé publique (par ex. ) pour le recopier dans votre presse papier :

Une possibilité est d'ouvrir votre fichier comportant la clé publique avec votre éditeur de texte favori (Notepad, TextEdit, gedit, etc). Dans le dialogue de sélection de fichiers de votre éditeur de texte, il est possible que vous ayez à activer l'option « Afficher les fichiers cachés »  pour trouver le fichier, car le répertoire   est caché. Parfois l'option « Afficher les fichiers cachés » est disponible en cliquant-droit dans le dialogue de sélection de fichier.

Les autres options sont :

It’s important you copy your SSH Public key exactly as it is written, without adding any newlines or whitespace. Copy the full text, including the "ssh-rsa" prefix, the key itself, and the email address suffix.
 * Sous Linux, exécutez et copiez manuellement la sortie dans le presse papier.
 * On Windows, you can open Git GUI, go to Help 🡒 Show Key, and then press "Copy To Clipboard" to copy your public key to your clipboard.
 * On macOS, you can run to copy the contents of the your public key file to your clipboard.

Ajouter sa clé publique SSH à son compte Gerrit

 * Connectez-vous à l'interface web de Gerrit. The username and password for your Gerrit are the same as for your Wikimedia Developer account.
 * Click on your username in the top right corner, then choose "Settings".
 * Dans le menu de gauche, cliquez sur Clés publiques SSH.
 * Collez votre clé publique SSH dans le champ correspondant et cliquez sur « Ajouter ».

Ajouter la clé privée SSH pour utiliser Git
Ouvrir la ligne de commande Git Bash.


 * Get ssh-agent running using
 * Be sure to use the accent, not the single quote  . (Vous pouvez copier et coller à partir de cette page si vous ne pouvez pas facilement utiliser ce caractère spécial.)
 * Be sure to use the accent, not the single quote  . (Vous pouvez copier et coller à partir de cette page si vous ne pouvez pas facilement utiliser ce caractère spécial.)


 * Ajoutez votre clé privée à l'agent. If you followed the steps above and your key has the default name, then the command is:


 * Connect to the Gerrit server via  to check if everything works as expected. Remplacez  par votre nom d'utilisateur comme indiqué dans vos paramètres Gerrit :

An example Gerrit SSH connection success message looks like this:
 * Be paranoid and compare that the "RSA key fingerprint" is the same as the SSH fingerprint for gerrit.wikimedia.org:29418. If it is the same, answer "Yes" to "Are you sure you want to continue connecting?". Ensuite, entrez la phrase de passe de votre clé.
 * Vous devrez obtenir un message « Welcome to Gerrit Code Review ». The last line should show "Connection to gerrit.wikimedia.org closed."
 * If you run into problems, use (replace  by your username). Le   va fournir une sortie verbeuse pour aider à résoudre les problèmes. Ensuite lisez les résolutions des problèmes Gerrit.

Télécharger le code avec Git
Faisons quelques essais en téléchargeant (nous disons « en clonant ») le répertoire sandbox. Exécutez ce qui suit, sur la ligne de commande Git Bash.

(Remplacer par votre nom d'utilisateur Gerrit. Et assurez-vous que l'URL commence par   et non par  ).

Ceci va copier l'historique entière et la base de code du dépôt de l'extension « sandbox » sur votre machine. Vous obtiendrez un répertoire de travail de la branche principale de l'extension (habituellement appelé « git master »). Entrez le nouveau répertoire (via la comande ) Maintenant vous pouvez voir le code et commencer à le modifier.

Se préparer à travailler avec Gerrit
Gerrit nécessite que votre message de validation possède un ID de modification. Cela ressemble à  en commençant par I (i majuscule). A chaque fois que vous amendez une validation pour améliorer un patch existant dans Gerrit, cet ID de modification reste le même, donc Gerrit le conçoit comme un nouvel ensemble de corrections relatif à la même modification de code.

There's a git add-on called git-review that adds a Change-ID line to your commits. L'utilisation de git-review est recommandée. Cela rend plus facile la configuration de votre clone de Git, pour soumettre une modification ou pour en rechercher une qui existe.

Installer git-review
Notez bien que Wikimedia Gerrit nécessite git-review version 1.27 ou plus récent.

Pour d'autres détails, veuillez lire Gerrit/git-review#Installation.

Font Awesome 5 brands linux.svg Linux

 * Use the graphical software package management tool of your Linux distribution to install the  package.
 * If git-review has not been packaged by your distribution, check git-review for other options such as installing git-review by using the pip Python package installer.
 * Si vous utilisez FreeBSD, installez git-review au travers des ports.

Font Awesome 5 brands windows.svg Windows

 * Veuillez lire git-review pour Windows.

Apple logo black.svg macOS

 * Pour OS X 10.11 El Capitan et ultérieur, appliquez la Méthode 2.
 * Dans les versions antérieures à la 10.11, utilisez l'installateur de paquets Python pip en suivant la Méthode 1.

Configurer git-review
L'hôte distant par défaut de Git est « origin ». Ce nom est aussi utilisé par les projets Wikimedia. Il faut dire à git-review d'utiliser cet hôte. Remplacez par votre nom d'utilisateur Gerrit :

Paramètrer git-review
Après avoir téléchargé un dépôt (cloné), vous devez l'activer pour git-review. Ceci se fait automatiquement la première fois que vous essayez de soumettre une validation, mais il est en général conseillé de le faire juste après avoir cloné. Vérifiez que vous êtes dans le répertoire du projet que vous avez cloné (sinon vous obtiendrez une erreur « fatal: Not a git repository » indiquant qu'il ne s'agit pas d'un répertoire Git). Puis exécutez cette commande :

Vers la fin de la sortie, vous devriez voir quelque chose comme ceci :

Ceci peut vous demander votre nom d'utilisateur Git, s'il est différent du nom de l'utilisateur du shell que vous utilisez.

Soumettre un patch
Make sure that you cloned the code repository that you are interested in (see here).

Make sure that you are in the directory of the code repository (the command tells you where exactly you are).

Mettre à jour le master
Assurez-vous que votre branche maître (master : la branche créée lorsque vous avez initialement cloné le dépôt) est encore à jour :

However, note that a few repositories use different terms (for example, the  repository has a   instead of a   branch).

Créer une branche
Créez d'abord une branche locale pour votre nouvelle modification. Replace below by a short but reasonably descriptive name (e.g.   if a corresponding Phabricator task exists for your changes, , or  ). Les autres personnes utiliseront également ce nom pour identifier votre branche.

Ceci va créer une nouvelle branche (appelée ) à partir du dernier 'master' et l'ouvrir pour vous. Dans l'exemple ci-dessus, nous avons appelé cette nouvelle branche.

Faire les modifications
Modifiez votre code local. Utilisez votre éditeur de texte préféré et modifiez un fichier. Dans l'exemple ci-dessous, nous modifions le fichier  en ajoutant un mot.

Puis fermez votre éditeur de texte et vérifiez les modifications que vous avez faites depuis la dernière validation, dans les fichiers eux-mêmes mais aussi dans le répertoire :

displays your changes in unified diff format: Removed lines have a minus prefix and added lines have a plus  prefix. Ces modifications ne sont pas encore « mises en réserve » (via  ) pour la validation prochaine.

Réserver les modifications avant de valider
Run to decide which of your changes should become part of your commit. It will display a list of all file(s) that you have changed within the directory. At this point, the output will display "no changes added to commit" as the last line.

Use  to make your changed file(s) become part of your next commit. In the example above we modified the file, so the command would be:

Any files you've changed that you have not passed to  will be ignored when running   in the next step.

Valider les modifications en réserve
Dès que vous êtes satisfait des modifications ajoutées via, vous pouvez transformer ces modifications en une validation dans votre dépôt local en utilisant

You will then be asked in your text editor to add a descriptive summary for your commit. You must follow the Commit message guidelines. This is what other people will see when looking at the history of changes in the code repository.

Enregistrez le message de validation et fermez votre éditeur de texte. Un sommaire (l'ID de la validation, votre ligne du sujet, les fichiers et les lignes modifiées) sera affiché.

Préparer la publication de la validation dans Gerrit
Synchronisez votre ensemble de corrections avec toute modification qui aurait déjà pu être faite sur la branche maître alors que vous étiez en train de travailler (c'est le rebasing). A partir de votre branche, exécutez :

Vous êtes maintenant prêt à mettre votre code dans Gerrit pour la relecture de code. Si vous avez fait plusieurs validations liées, vous devez les fusionner en une seule validation pour la revue.

Placer vos validations dans Gerrit
Si vous avez suivi les indications ci-dessus et que vous avez installé  et exécuté , alors la commande pour mettre les modifications dans Gerrit est :

L'option  indique à l'outil git-review de ne pas faire de rebase avant de soumettre la modification à Gerrit.

Si tout se passe bien, vous recevrez une confirmation et un lien vers l'ensemble de corrections dans Gerrit. Dans l'exemple ci-dessus, ce lien est : https://gerrit.wikimedia.org/r/#/c/sandbox/+/563720

Bravo ! Votre patch est dans Gerrit et nous l'espérons, sera relu bientôt!

Afficher les modifications / Etapes suivantes
Ouvrez le lien vers votre ensemble de modifications de Gerrit dans un navigateur web.

Sous « Fichiers », après avoir cliqué sur la flèche vers le bas à l'extrémité droite de chaque fichier de la liste, vous pouvez voir un diff de vos modifications par fichier : les anciennes lignes sont affichées en rouge et vos nouvelles lignes sont en vert.

Si votre validation a généré un ticket dans Phabricator, un commentaire sera automatiquement ajouté dans la tâche Phabricator si vous avez suivi les indications du message de validation. Si vous ne l'avez pas fait, vous pouvez soit corriger votre message de validation (en créant un ensemble de corrections mis à jour), ou en ajoutant manuellement un commentaire sur ce ticket Phabricator qui inclut un lien vers votre ensemble de corrections dans Gerrit.

Autres situations communes
Voir aussi l'usage avancé de Gerrit si votre cas n'est pas traité ici.

Rassembler plusieurs validations en une seule avec rebase
Si vous faites plusieurs validations liées sur votre répertoire local avant de vouloir les soumettre pour relecture, vous devrez rassembler ces validations (merge) dans une validation unique.

The  or   option allows you to change (rewrite) your commit history. For each commit, you can modify and change the commit message, add or remove files, or perform other modifications.

D'abord vous devez dire à Git jusque où vous voulez remonter en arrière. Pour obtenir une liste de toutes les modifications réalisées sur votre branche :

You can also limit the displayed list of recent changes. means pull the last three commits:

Après avoir entré cette commande, votre éditeur de texte affichera vos modifications dans l'ordre inverse ainsi qu'une liste de commandes utilisables :

Since we only want to send one commit to review, we will squash the last two commits into the first. Hence change all but the first "pick" to "squash":

pick aa8cf1d Adding method customFilterFunctionGetRiskyCountryCodeScore to GatewayAdapter. squash 38828e2 Adding $wgDonationInterfaceCustomFiltersFunctionsRiskyCountries to donationinterface.php squash be33007 Fix a typo

When you finished picking and squashing and saved the file, another file will open in your text editor to allow you get to edit and merge your commit messages. Be careful to only keep one of the Change-Id lines and have it be at bottom of the message after one empty line.

Your messages from your previous commits will automatically be placed in this message:

N'oubliez pas de mettre votre message de résumé (mis à jour) dans la validation. Dans ce cas le nouveau message de résumé sera :

(mingle-fr-2012-69) Adding a custom filter for risky countries.

Si tout se passe bien, vous devriez voir un message rebase de succès :

Après cela, envoyez votre patch pour relecture :

Vous devriez voir un message comme celui-ci indiquant que votre revue Git est partie sur Gerrit (dans cet exemple, vers https://gerrit.wikimedia.org/r/7187) :

Amending a change (your own or someone else's)
Sometimes, you might need to amend a submitted change. You can amend a change as long as the change hasn't been merged yet.

You can amend your own changes. To amend changes submitted by someone else, you need to be a member of Gerrit's Trusted-Contributors group. To become a member of Trusted-Contributors, find someone who is a member and ask them to add you. The group is viral in that members can add new members, use your powers responsibly.

Rebase to bring your local branch up to date with the remote. It's best to make rebase updates a separate patch, so that your code reviewers have an easy time seeing what changes you've made. Assuming you are using Gerrit, you can do this by clicking the "Rebase Change" button when viewing your patch in Gerrit's web interface.

Hard reset and checkout the change with this command: (BEWARE:  performs a hard reset that destroys all local changes. Stash or commit changes first which you wish to preserve!)

For example:

Notez que si vous avez déjà la modification présente dans une branche de votre dépôt local, il suffit de l'ouvrir (check out) à la place :

For example:

Ensuite, faites quelques modifications avec votre éditeur de texte favori.

the files as needed, then commit the change (ensuring you are amending the commit):

Validez la modification :

The  is important here. It tells git-review to not rebase your change against master, which clutters diffs between patch set 1 and 2.

Push to a branch different than master
Above, the commit was pushed to the master branch. The branch name only appeared as the topic of the commit in the Gerrit UI. If you really want to push to a different branch than master, you have to push via.

Editing via the web-interface
If you're logged in to Gerrit, you can also create code changes directly within the web interface. This can be useful for making small patches, or for non-developers to contribute small fixes. Done!
 * 1) Go to https://gerrit.wikimedia.org/r/admin/projects and choose the code repository that you want to edit.
 * 2) Select "Commands" in the sidebar
 * 3) Click "Create Change"
 * 4) Set branch to "master" (if you don't want to use master branch you can use the other branches available for that project)
 * 5) Set the topic to something of your choosing (e.g. "copy-edit" - must be all-one-string) (optional)
 * 6) Write a description ("commit summary") in the big text field by following Gerrit/Commit message guidelines. (Example)
 * 7) Click "Create"
 * 8) In the upper right corner, click the "Edit" button
 * 9) Under "Files", click "ADD/OPEN/UPLOAD" button
 * 10) Type the folder/file path for the file you wish to edit (e.g. i18n/en.json) and click "Open"
 * 11) Find the line(s) you want to change, and change them.
 * 12) Click "Save"
 * 13) Click "Close"
 * 14) Click "Publish edit"
 * 15) Click the button "Start Review"

If you need to change the commit message of an existing changeset, you can use these steps:
 * 1) Go to the changeset itself. Example URL: https://gerrit.wikimedia.org/r/c/1234567890 (replace the ID at the end)
 * 2) In the "Files" section, click "Commit message"
 * 3) In the upper right corner, click the "Edit" button
 * 4) Make changes to the commit summary.
 * 5) In the upper right corner, click "Save"
 * 6) In the upper right corner, click "Close"
 * 7) In the upper right corner, click "Publish edit"

How code is reviewed in Gerrit
Code review is an essential part of our contribution workflow. The principle is basic: any patch must be reviewed by others before being merged.

This means that your code will need reviewers. Check our advice for getting reviews.

Review before merge
It's important to us to have a review-before-merge workflow for MediaWiki core and also for any extension we deploy. We will also offer that option to any extension author who wants it for their extension. The one exception is localisation and internationalisation commits, which will be able to be pushed without review.

Who can review? Gerrit project owners
After creating a Developer account, anyone can comment on commits and express criticism and approvals. Anyone can give a nonbinding "+1" to any commit. However, for any given repository ("Gerrit project"), only a small group of people will have the ability to approve code within Gerrit and merge it into the repository. This superapproval is a "+2" even though that's a misleading name, because two +1 approvals DO NOT add up to a +2. These people are "Gerrit project owners".

How to comment on, review, and merge code in Gerrit




Anyone can comment on code in Gerrit.

Viewing and commenting on code

 * Make sure that you have a developer account.
 * Log in to Gerrit. If you know the changeset you want to look at (URL will look like https://gerrit.wikimedia.org/r/#/c/23939/ ), go to that. Otherwise, use the search box. You can search by author ("Owner"), Gerrit project, branch, changesets you've starred, etc. The Gerrit search documentation covers all of the different search operators you can use.
 * The changeset has a few fields, links and buttons:
 * Assignee. An optional field to make a single person responsible for handling reviewing the changeset. This should only be set if the assignee has agreed.
 * Reviewers. 'jenkins-bot' is the autoreviewer that auto-verifies anything that passes the Jenkins tests. It will report a red or green mark depending on whether the build passes.
 * The "Add reviewer" button under Reviewers: in the upper left corner manually request review from someone. It'll show up in their Gerrit dashboard.
 * Under Files, Expand All opens the diff for each file below. You can double-click on a line and then press the C key to comment on that line, then click "Save" to save the draft comment. Then, at the top of the page click the "Reply" button to publish your comment.
 * Reply adds your comments to a changeset, including an overall comment and/or inline comments you added (see above).
 * If, upon code review, you approve, use "Code-Review: +1" under "Reply"; otherwise, use "Code-Review: -1" to disapprove. These numbers are nonbinding, won't cause merges or rejections, and have no formal effect on the code review.
 * Abandon (you'll see this if you wrote this diff). This action removes the diff from the list to review, but leaves it in Gerrit for archival purposes.
 * The "Only Comments" switch allows to hide reviews by non-human bots. See https://phabricator.wikimedia.org/T48148#6294913 for an example.

Comparing patch sets
Every time you amend your commit and submit it for review, a new patch set is created. You can compare the different patch sets like this:


 * Under Files, select either Expand All or choose a specific file listed to open that file.
 * On the left side under Patch Set, Base is preselected. On the right of the screen under Patch Set, the latest patch set is preselected. Adjust the selected patch sets to your needs.

Formally reviewing and merging or rejecting code
If you are one of the Gerrit project owners, you'll also see:
 * Abandon button
 * under Reply, additional Code-Review options to +2 (approve) or -2 (veto) a diff, and a Post button (publish your comment and merge diff into the branch, in 1 step)
 * Submit button (merge -- only useful if you or someone else has already given a +2 approval to the diff, but not merged it)

And once you've merged something into the example Gerrit project you'll see it in https://gerrit.wikimedia.org/r/plugins/gitiles/test/mediawiki/extensions/examples/.

If you merged a commit that references a task in Phabricator and that commit is supposed to fix that task completely, please go to that task and change its status to "Resolved" (via the Add Action… 🡒 Change Status dropdown). Also reference the merge ID if gerritbot has not already posted it in that task.

Résolution des problèmes
For problems and how to solve them, see Gerrit/Troubleshooting.

Voir aussi
Also useful are these pages:
 * Download from Git
 * wikitech:Help:Getting Started
 * Gerrit
 * Gerrit/git-review
 * Gerrit/Tutorial/tl;dr
 * Gerrit/TortoiseGit tutorial
 * Wikimedia Gerrit Patch Uploader