Gerrit/Tutoriel

This page is a translated version of the page Gerrit/Tutorial and the translation is 99% complete.
Outdated translations are marked like this.
Other languages:

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 ? : Gerrit/Tutoriel/Abrégé
  • Pour les utilisateurs chevronnés, Gerrit/Advanced usage 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 : command. 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 : command variable.

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 +2 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 documentation officielle.

Installation

  Linux

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

  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.
Si vous souhaitez une intégration supplémentaire au shell Windows, voyez Gerrit/TortoiseGit tutorial .

  macOS

  • Installez le gestionnaire de paquets Homebrew puis exécutez la commande brew install git – 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 gerrituser par votre propre nom d'utilisateur Gerrit, et gerrituser@example.com par votre propre adresse courriel :

git config --global user.email "gerrituser@example.com"

git config --global user.name "gerrituser"

Pour voir vos variables de configuration actuelles qui régissent le comportement de Git, utilisez git config -l.

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 :

ls ~/.ssh

La commande va lister les fichiers se trouvant dans le répertoire (caché) .ssh. Si le répertoire existe déjà dans votre système et si la sortie liste un fichier qui s'appelle id_rsa.pub, 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 gerrituser@example.com 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.

 
Entrer la commande ssh-keygen

ssh-keygen -t rsa -C "gerrituser@example.com"

Entrez une phrase secrète (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. Si vous en utilisez un qui est facile à se remémorer, il sera plus facile de le deviner ou de le forcer. Si vous en choisissez un qui est aléatoire, il sera difficile de s'en rappeler, et vous devrez donc le noter quelque part. Les deux sont très mauvais. C'est pourquoi vous utilisez les clés ssh. Mais utiliser une clé ssh sans phrase secrète 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 secrète. Pour entrer une longue phrase de passe à chaque fois que vous utilisez la clé, il existe un outil appelé ssh-agent. Il peut garder votre phrase secrète en sécurité. Si vous êtes sous macOS ou Linux, alors vos clés peuvent être sauvegardées dans la chaîne des clés de votre système même pour vous faciliter la vie.

La commande ssh-keygen va créer 2 fichiers dans le répertoire ~/.ssh :

  • ~/.ssh/id_rsa : votre clé privée SSH (pour l'identification)
  • ~/.ssh/id_rsa.pub : votre clé publique SSH

Copier sa clé publique SSH

Récupérez le contenu du fichier de votre clé publique (par ex. id_rsa.pub) 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 .ssh 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 :

  • Sous Linux, exécutez cat ~/.ssh/id_rsa.pub et copiez manuellement la sortie dans le presse papier.
  • Sous Windows, vous pouvez ouvrir l'interface Git, aller sur la touche d'affichage de l'aide 🡒 , et presser « Copier vers le presse papier » pour y entrer votre clé publique.
  • Sous macOS, vous pouvez exécuter pbcopy < ~/.ssh/id_rsa.pub pour copier le contenu du fichier de votre clé publique vers votre presse-papier.

Il est important de recopier votre clé publique SSH exactement comme elle est écrite sans y ajouter de passage à la ligne ni d'espaces. Copier le texte complet, y compris le préfixe « ssh-rsa », la clé elle-même, et le suffixe de l'adresse courriel.

Ajouter sa clé publique SSH à son compte Gerrit

  • Connectez-vous à l'interface web de Gerrit. Votre nom d'utilisateur ainsi que le mot de passe de Gerrit sont les mêmes que ceux de votre compte développeur Wikimedia.
  • Cliquez sur votre nom d'utilisateur dans le coin supérieur droit puis choisissez « Paramètres »
  • 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.

  • Activez l'agent ssh-agent en utilisant :
eval `ssh-agent`
Vérifiez bien d'utiliser l'accent $1, et non pas l'apostrophe $2.
eval `ssh-agent`
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.[1] Si vous avez suivi les étapes ci-dessus et que votre clé a le nom par défaut id_rsa, alors la commande sera :
ssh-add .ssh/id_rsa
  • Connectez-vous au serveur Gerrit via ssh pour vérifier si tout fonctionne correctement. Remplacez gerrituser par votre nom d'utilisateur comme indiqué dans vos paramètres Gerrit :
ssh -p 29418 gerrituser@gerrit.wikimedia.org
  • Soyez paranoïaque et vérifiez que « l'empreinte de la clé RSA » est la même que l'empreinte SSH pour gerrit.wikimedia.org:29418. Si c'est la cas, répondez « Yes » à la question « Are you sure you want to continue connecting ? ». Ensuite, entrez la phrase secrète de votre clé.
  • Vous devrez obtenir un message « Welcome to Gerrit Code Review ». La dernière ligne doit afficher «  Connection to gerrit.wikimedia.org closed. »
  • Si vous rencontrez des difficultés, utilisez ssh -p 29418 -v gerrituser@gerrit.wikimedia.org (remplacez gerrituser par votre nom d'utilisateur). Le -v va fournir une sortie verbeuse pour aider à résoudre les problèmes. Ensuite lisez les résolutions des problèmes Gerrit.

Un exemple de message de connexion SSH Gerrit réussie ressemble à ceci :

  Example:

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.

git clone ssh://gerrituser@gerrit.wikimedia.org:29418/sandbox (Remplacer gerrituser par votre nom d'utilisateur Gerrit. Et assurez-vous que l'URL commence par ssh: et non par https:).

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 cd sandbox) Maintenant vous pouvez voir le code et commencer à le modifier.

En clonant le dépôt de Sandbox vous n'obtiendrez pas la configuration de l'environnement de développement ni une installation opérationnelle de MediaWiki. (Pour cela il vous faudra avoir le noyau MediaWiki et mettre le code que vous avez cloné à un endroit accessible par votre serveur web.) Voir Télécharger de Git comment télécharger le noyau MediaWiki, les extensions, les habillages, ou tout autre dépôt de projet de Git hébergé sur gerrit.wikimedia.org.

Se préparer à travailler avec Gerrit

Gerrit nécessite que votre message de validation possède un ID de modification. Cela ressemble à Change-Id: Ibd3be19ed1a23c8638144b4a1d32f544ca1b5f97 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.

Il existe un greffon Git appelé git-review qui ajoute une ligne avec l'ID de modification à vos validations. 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 l'installation.

  Linux

  Windows

  macOS

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

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 gerrituser par votre nom d'utilisateur Gerrit :

git config --global gitreview.remote origin

git config --global gitreview.username gerrituser

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 :

git review -s --verbose

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

  Example:

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

Si vous n'avez pas pu installer git-review, vous pouvez utiliser le téléverseur de patch Gerrit pour soumettre une correction.

Soumettre un patch

Assurez-vous d'avoir cloné le dépôt de code qui vous intéresse (voir ici).

Vérifiez d'être dans le répertoire du dépôt de code (la commande pwd vous indique où vous vous trouvez exactement).

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 :

git pull origin master

Notez néanmoins que seuls certains dépôts utilisent des termes différents (par exemple, le dépôt operations/puppet a une branche production au lieu de master).

Créer une branche

Créez d'abord une branche locale pour votre nouvelle modification. Remplacez BRANCHNAME ci-dessous par un nom court et suffisamment descriptif (par exemple T1234 si une tâche Phabricator correspondante existe pour vos modifications, cleanup/some-thing, ou badtitle-error). Les autres personnes utiliseront également ce nom pour identifier votre branche.

git checkout -b BRANCHNAME origin/master

  Example:

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

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

git diff

  Example:

git diff affiche vos modifications dans le format diff unifié: les lignes supprimées sont préfixées par un signe moins (-) et les lignes ajoutées sont préfixées par un signe plus (+). Ces modifications ne sont pas encore « mises en réserve » (via git add) pour la validation prochaine.

Réserver les modifications avant de valider

Exécuter git status pour décider quels changements devront faire partie de votre validation. Cela va afficher une liste de tous les fichiers que vous avez modifiés dans le répertoire. A cette étape, la sortie va afficher « no changes added to commit » sur la dernière ligne.

Utilisez git add pour que le/les fichier(s) que vous avez modifiés fassent partie de votre prochaine validation. Dans l'exemple ci-dessus nous avons modifié le fichier README.md, donc la commande sera :

git add README.md Tout fichier modifié que vous n'avez pas passé à git add sera ignoré lorsque vous exécuterez git commit dans la prochaine étape.

A tout instant vous pouvez toujours vérifier les modifications déjà mises en réserve, en exécutant git status. Après avoir exécuté git add, git status ne va plus afficher la ligne « aucun changement ajouté pour la validation ».
Vous pouvez aussi utiliser git diff --cached pour voir quelles modifications sont dans la réserve et qui feront partie de la prochaine validation. La sortie sera la même que pour la commande git diff ci-dessus.

Valider les modifications en réserve

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

git commit

  sandbox/.git/COMMIT_EDITMSG:

Ensuite, on vous demandera dans votre éditeur de texte d'ajouter un résumé descriptif de votre validation. Vous devez suivre les instructions du message de validation. C'est ce que les autres verront lorsqu'ils liront l'historique des modifications dans le dépôt du code.

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

Vous pouvez répéter cette étape plusieurs fois jusqu'à ce que vous obteniez un ensemble de modifications que vous voulez appliquer à la branche maître.

Lorsque vous git commit, vous validez (commit) votre copie locale.

Cela signifie que vous pouvez valider autant de fois que vous voulez sans perturber potentiellement le travail d'un autre développeur du projet.

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 :

git pull --rebase origin master

  Example:
git pull --rebase origin master va récupérer les nouvelles validations du distant et va les appliquer (rebase) sur vos validations locales.

Cela va temporairement mettre de côté les modifications que vous avez faites dans votre branche, et appliquer à votre branche de travail l'ensemble des modifications apparues sur la branche maître; ensuite cela va fusionner (recommit) toutes les modifications que vous avez faites à nouveau dans la branche. En faisant cela, vous éviterez les conflits lors des fusions à venir.

De plus, cela vous donne une possibilité de tester vos modifications sur le dernier code de la branche maître.

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é git-review et exécuté git review -s, alors la commande pour mettre les modifications dans Gerrit est :

git review -R

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

  Example:

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.

L'algorithme diff de Gerrit (appelé jGit) est un peu différent de celui que Git utilise par défaut. Les différences affichées par Gerrit peuvent ne pas resembler aux différences affichées par Git sur votre machine.

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.

L'option --interactive ou -i vous permet de modifier (corriger) l'historique de votre validation. Pour chaque validation, vous pouvez modifier et changer le message associé, ajouter ou supprimer des fichiers, ou réaliser d'autres 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 :

git rebase -i origin/master

Vous pouvez également limiter la liste des dernières modifications affichées. HEAD~3 signifie retirer les trois dernières validations :

git rebase -i HEAD~3

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

  Example:

Si nous voulons seulement envoyer en relecture une seule validation, nous allons inclure les deux dernières validations dans la première. A partir de là, changer tout en « squash » sauf le premier « pick » :

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

Lorsque vous avez terminé avec les « pick » et les « squash » et que vous avez enregistré le ficher, un autre fichier va s'ouvrir dans votre éditeur de texte pour que vous puissiez modifier et fusionner vos messages de validation. Vérifiez à ne garder qu'une seule des lignes comportant un identificateur de changement tout en bas du message et gardez-la précédée d'une ligne vide.

Les messages correspondants à vos validations précédentes seront automatiquement placés dans ce message :

  Example:

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.
En fonction de quel Change-Id vous voulez utiliser, pour regrouper une validation dans une validation existante (une qui figure déjà dans Gerrit), vous devez saisir le Change-Id qui appartient à celle à laquelle vous avez l'intention de soumettre un nouvel ensemble de corrections (c'est à dire la validation qui va survivre). Si vos validations sont nouvelles et ne sont pas dans Gerrit, l'Id de modification que vous utilisez n'a pas d'importance.

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

  Example:

Après cela, envoyez votre patch pour relecture :

git review

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

  Example:

Amender une correction (la vôtre, ou celle d'une autre personne)

Quelque fois vous pourriez avoir à amender une modification soumise. Vous pourvez amender une modification tant que celle-ci n'a pas encore été fusionnée.

Vous pouvez amender vos propres modifications. Pour amender les corrections soumises par une autre personne, vous devez être un membre du groupe des contributeurs confirmés (Trusted-Contributors) de Gerrit. Pour faire partie des Trusted-Contributors, recherchez quelqu'un qui est déjà membre de ce groupe et demandez-lui de vous y ajouter. Le groupe est viral dans le sens où les membres eux-mêmes peuvent ajouter les nouveaux candidats; utilisez vos droits sous votre responsabilité.

Faites un « rebase » pour remettre à jour votre branche locale avec le contenu actuel du distant. Il est mieux de faire la mise à jour d'une correction séparée, à l'aide d'un rebase de sorte à ce que vos relecteurs aient le temps de voir les modifications que vous avez faites. En supposant que vous utilisez Gerrit, vous pouvez faire cela en cliquant sur le bouton de mise à jour par rebase (Rebase Change) lorsque vous affichez votre correction dans l'interface web de Gerrit.

Réinitialiser le matériel et extraire les modifications avec cette commande : (ATTENTION : git review -d provoque une réinitialisation du système qui fait perdre toutes les modifications locales. Mettez d'abord en réserve ou validez les modifications que vous voulez mettre de côté ! )

git review -d changenumber Par exemple : git review -d 9332

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 :

git checkout BRANCHNAME Par exemple : git checkout review/gerrituser/2012/bug12345

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

git add les fichiers si nécessaire, ensuite validez les modifications (en vérifiant de bien amender la validation) :

git add Example/Example.body.php

git commit --amend --all

N'UTILISEZ PAS le drapeau -m pour spécifier un résumé de validation : cela va réécraser le résumé précédent et regénérer le Change-Id. A la place, utilisez l'éditeur de texte pour modifier le résumé de la validation (dans le fichier .git/COMMIT_EDITMSG si nécessaire, et laissez la ligne Change-Id intacte.

Validez la modification :

git review -R

Le -R est important ici. Cela indique à git-review de ne pas faire un rebase de vos modifications sur la branche master , ce qui somme les diff entre les patchs 1 et 2.

Pousser sur une branche différente de la branche master

Ci-dessus, la validation a été poussée sur la branche master. Seul le nom de la branche apparait comme sujet de la validation dans l'interface utilisateur Gerrit. Si vous voulez réellement pousser sur une branche différente du master, vous devrez pousser via git review <branch name>.

Modifier via l'interface web

Si vous êtes connecté à Gerrit, vous pouvez aussi créer les modifications de code directement dans l'interface web. C'est très pratique pour les petites corrections, ou pour les non développeurs, afin qu'il puissent contribuer en faisant des modifications ponctuelles.

  1. Aller dans https://gerrit.wikimedia.org/r/admin/projects et choisir le dépôt de code à modifier.
  2. Selectionner « Commands » dans la barre latérale
  3. Cliquer sur « Create Change »
  4. Fixer la branche à master (si vous ne voulez pas utiliser la branche master vous pouvez utiliser les autres branches disponibles dans ce projet)
  5. Fixez le sujet à ce que vous voulez (par exemple copy-edit - doit tenir sur une seule ligne) (facultatif)
  6. Ecrivez un résumé de la validation (commit summary) dans la grande zone de texte en suivant les recommandations des messages. (Exemple)
  7. Cliquer sur « Create »
  8. Dans le coin supérieur droit, cliquer sur le bouton « Edit »
  9. Dans « Files » , cliquer sur le bouton ADD/OPEN/UPLOAD »
  10. Entrez le chemin dossier/fichier du fichier que vous souhaitez modifier (par exemple i18n/en.json) et ouvrez en cliquant sur Open
  11. Cherchez la/les ligne(s) à modifier et faites vos corrections.
  12. Cliquer sur « Save »
  13. Cliquer sur « Close »
  14. Cliquer sur « Publish edit »
  15. Cliquer sur le bouton « Start Review »

C'est fait !

Si vous devez modifier le message de validation d'un ensemble de corrections déjà existant, vous pouvez suivre les étapes suivantes :

  1. Allez sur l'ensemble de modifications. Exemple d'URL: https://gerrit.wikimedia.org/r/c/1234567890 (remplacer l'ID de la fin)
  2. Dans la section « Files », cliquer sur « Commit message »
  3. Dans le coin supérieur droit, cliquer sur le bouton « Edit »
  4. Effectuer les modifications dans le résumé de la validation.
  5. Dans le coin supérieur droit, cliquer sur « Save »
  6. Dans le coin supérieur droit, cliquer sur « Close »
  7. Dans le coin supérieur droit, cliquer sur « Publish edit »

Comment se fait la relecture du code dans Gerrit

La relecture de code est une partie essentielle du flux de travail de nos contributions. Le principe est élémentaire : toute correction doit être relue par les autres avant de pouvoir être fusionnée.

Cela signifie que votre code aura besoin d'être relu. Voyez nos conseils pour trouver les relectures à faire.

Relecture avant de fusionner

Il est important pour nous d'avoir un flux de travail de la revue de code avant la fusion pour le noyau MediaWiki ainsi que pour toute extension déployée par nous. Nous proposerons également cette option à tout auteur qui la souhaite pour son extension. La seule exception sont les validations de localisation et d'internationalisation, qui peuvent être poussées sans relecture.

Qui peut faire la relecture et les propriétaires de projet Gerrit

Après avoir créé un compte de développeur, chacun peut commenter les validations et exprimer des critiques ou des approbations. Chacun peut attribuer liobrement un +1, à toute validation. Néanmoins, pour tout dépôt de projet de Gerrit, seul un groupe restreint de personnes auront la possibilité d'approuver le code dans Gerrit et de le fusionner dans le dépôt. Ces super droits d'approbation sont un +2 même si c'est une nom un peu trompeur, car deux approbations +1 NE DONNENT PAS un +2. Ces personnes sont appelées les « propriétaires du projet Gerrit ».

Comment faire un commentaire, une relecture, ou fusionner le code dans Gerrit

 
Exemple d'ensemble de modifications fraîchement téléversé vu dans l'interface web de Gerrit
 
Diff côte-à-côte dans l'interface web de Gerrit

Chacun peut commenter le code dans Gerrit.

Afficher et commenter le code

  • Assurez-vous d'avoir compte développeur.
  • Connectez-vous sous Gerrit. Si vous connaissez l'ensemble des corrections que vous voulez afficher, allez-y (l'URL est de la forme https://gerrit.wikimedia.org/r/#/c/23939/). Sinon, utilisez la boîte de recherche. Vous pouvez chercher par auteur (Owner),par projet Gerrit,par branche, ensemble de corrections que vous avec marqués, etc. La documentation sur la recherche dans Gerrit couvre tous les différents opérateurs de recherche que vous pouvez utiliser.
  • L'ensemble de corrections possède quelques champs, liens et boutons :
    • Assignee un champ optionnel pour assigner un reponsable de la gestion de la relecture de l'ensemble de corrections. Ceci ne doit être fait qu'avec l'accord de la personne désignée.
    • Reviewers. 'jenkins-bot' est le relecteur automatique qui vérifie implicitement tout se qui est soumis aux tests Jenkins. Il positionne une marque verte ou rouge si la compilation a réussi ou pas.
    • Le bouton « Add reviewer » pour ajouter un relecteur, sous Reviewers:, dans le coin supérieur gauche va demander manuellement la relecture à quelqu'un. Cela sera indiqué dans son tableau de bord Gerrit.
    • Sous Files, Expand All ouvre le diff pour chaque fichier dessous. Vous pouvez double cliquer sur une ligne et presser la touche C pour laisser un commentaire sur cette ligne, puis cliquer sur « Save » pour enregistrer votre commentaire. Ensuite, en haut de la page, cliquez sur le bouton « Reply » pour publier vos commmentaires.
    • Reply ajoute vos commentaires à un ensemble de corrections, y compris le commentaire global et/ou les commentaires en ligne que vous avez ajoutés (voir ci-dessus).
      • Si lors de la relecture de code, vous approuvez, utilisez « Code-Review: +1 » sous « Reply »; sinon utilisez « Code-Review: -1 » pour montrer que vous n'approuvez pas la modification. Ces numéros ne sont pas liés, ne provoqueront pas de fusion ni de rejets, et n'ont pas d'effet formel sur la relecture du code.
    • Abandon (vous verrez cela si vous avez écrit ce diff). Cette action supprime le diff de la liste de relecture, mais le laisse dans Gerrit à des fins d'archivage.
  • Le sélecteur «  Only Comments » permet de masquer les relectures au robots non humains. Voir https://phabricator.wikimedia.org/T48148#6294913 pour un exemple.

Comparer des ensembles de corrections

A chaque fois que vous amendez votre validation, et que vous la soumettez à la relecture, un nouvel ensemble de corrections est créé. Vous pouvez comparer les différents ensembles de corrections ainsi :

  • Sous Files, sélectionnez soit Expand All ou un fichier particulier listé que vous voulez ouvrir.
  • Du côté gauche, sous Patch Set, la Base est préselectionnée. A droite de l'écran, sous « Patch Set », le dernier ensemble de corrections est présélectionné. Ajustez les ensembles de patchs sélectionnés selon vos besoins.

Relecture formelle et fusion ou rejet du code

Si vous êtes l'un des propriétaires du projet Gerrit, vous verrez également :

  • bouton Abandon
  • sous Reply, il y a les options supplémentaires de Code-Review à +2 (pour approuver) et -2 (pour rejeter) un diff, et un bouton Post (pour publier votre commentaire et fusionner le diff dans la branche, en une seule passe)
  • le bouton Submit (fusionner -- n'est utile que si vous, ou une autre personne a déja attribué un +2 au diff, mais ne l'a pas encore fusionné).

Une fois que la fusion est faite dans le projet exemple de Gerrit, vous pourrez la voir dans https://gerrit.wikimedia.org/r/plugins/gitiles/mediawiki/extensions/examples/.

Si vous fusionnez une validation qui référence une tâche de Phabricator et que cette validation est supposée corriger complètement cette tâche, veuillez aller dans cette tâche pour mettre son état à « Resolved » (par le menu déroulant Add Action… 🡒 Change Status ). Renseigner également l'ID de la fusion si gerritbot ne l'a pas déja inséré dans cette tâche.

Résolution des problèmes

Pour les problèmes et la manière de les résoudre, voir Gerrit/Troubleshooting.

Voir aussi

Les pages suivantes sont également utiles :

Guides tiers à propos de Git

Documents historiques

Références

  1. Si en tant qu'utilisateur Ubuntu vous avez un message « Permission denied (publickey) » relatif au rejet dû à la clé publique, veuillez lire cette page d'aide