Jump to content

Gerrit/Tutoriel

From mediawiki.org
This page is a translated version of the page Gerrit/Tutorial and the translation is 85% complete.
Outdated translations are marked like this.
Si vous avez l'expérience des lignes de commande et de Git, utilisez le guide condensé how-to à la place.

Ceci est un tutoriel qui explique comment utiliser Git pour créer et modifier les corrections dans Gerrit.

  • Pour les documents de référence sur les tâches spécifiques, consultez Gerrit/Utilisation avancée à la place.
  • 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 : commande. 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 : commande 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.

Créer un compte Wikimedia développeur

Si vous n'avez pas encore de compte développeur Wikimedia, créez-le. 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 [$url liste des clients maintenus par le projet Git]. Pour d'autres instructions d'installation voir la [$url documentation officielle].

Installation

Follow Installing Git to learn how to install git on your operating system.

Configurer Git

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

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, $2 par votre propre adresse courriel, et $3 par votre nom d'utilisateur tel qu'il est connu de votre shell (choisi quand le compte développeur Wikimedia a été créé) : Replace gerrituser@example.com with your own email address. And, replace shell_user with the shell username (chosen when you created the Wikimedia Developer account):

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

git config --global user.name "Gerrituser"

git config --global url."ssh://shell_user@gerrit.wikimedia.org:29418/".insteadOf "https://gerrit.wikimedia.org/r/"

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. Depuis août 2021, l'équipe Wikimedia Sécurité recommande que les utilisateurs qui créent des clés SSH, utilisent le type ed25519 pour une sécurité optimale et pour des raisons de performance.

Obtenir votre clé SSH

Follow SSH keys#Generating a new SSH key.


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 »
  • Cliquez sur Clés SSH dans le menu de gauche.
  • Collez votre clé publique SSH dans le champ correspondant et cliquez sur « ADD NEW SSH KEY ».

Tester la connexion SSH de Gerrit

Connectez-vous au serveur Gerrit via ssh pour vérifier si tout fonctionne correctement. Remplacez shell_user par votre nom d'utilisateur du shell comme indiqué dans vos paramètres Gerrit :

ssh -p 29418 shell_user@gerrit.wikimedia.org
  • Soyez consciencieux et vérifiez que « l'empreinte de la clé ed25519 » 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 shell_user@gerrit.wikimedia.org (remplacez shell_user par votre nom d'utilisateur du shell). 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

Bac à sable

Si vous voulez essayer d'utiliser Gerrit, vous pouvez télécharger (en « clonant ») le dépôt utilisé par ce tutoriel et appelé sandbox.

Exécutez ce qui suit, sur la ligne de commande Git Bash.

git clone https://gerrit.wikimedia.org/r/sandbox

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.

Dépôts existants

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.

Vagrant

Si vous avez téléchargé MediaWiki ou les extensions en utilisant Vagrant, assurez-vous que vous avez configuré Git pour pousser votre code via SSH au lieu de HTTPS.

Se préparer à travailler avec Gerrit

Page principale : Gerrit/git-review

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, pour soumettre une correction, vous pouvez utiliser le téléverseur de patch Gerrit ou le tutoriel Gerrit/Web .

Par défaut git-review utilise la branche master. Si le dépôt sur lequel vous travaillez utilise une autre branche, par exemple main, vous devez définir la variable de configuration gitreview.branch. Ceci peut être fait à l'aide de la commande suivante (où main est le nom de la branche) :

git config --add gitreview.branch main

Soumettre un patch

Assurez-vous d'avoir cloné le dépôt de code qui vous intéresse (voir le téléchargement via Git ci-dessus).

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 la branche principale de développement

Assurez-vous que votre branche principale de développement (la branche créée lorsque vous avez initialement cloné le dépôt) est encore à jour :

git pull origin master

Notez néanmoins que certains dépôts utilisent un noms différent pour leur branche principale de développement (par exemple main au lieu de master, ou 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-something, 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 cleanup-something.

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

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!

<span id="If_git review_fails">

Echec de git review -R

Si on vous demande d'entrer vos données personnelles (nom d'utilisateur et mot de passe) après avoir lancé git review, cela signifie que Git n'a pas encore été configuré pour utiliser SSH.

Review the steps at #Set up Git. In particular, run the following command:

git config --global url."ssh://shell_user@gerrit.wikimedia.org:29418/".insteadOf "https://gerrit.wikimedia.org/r/"

Il n'y a pas de problème à le refaire si vous ne vous souvenez pas l'avoir déjà fait. Remplacez shell_user par le nom d'utilisateur du shell pour votre compte développeur Wikimedia.

If you get a Permission denied (publickey). fatal: Could not read from remote repository., review the instructions at Clés SSH to make sure your ssh agent is running and your identity is added. Si vous fermez la fenêtre de votre shell Git Bash, vous serez déconnecté et devrez suivre à nouveau ces instructions.

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

Réinitialiser le matériel et extraire les modifications avec cette commande :

git review -d changeNumber Par exemple : git review -d 1814356

Voir changeNumber dans Gerrit. Il s'agit du numéro à six chiffres dans l'URL de votre page de revue de code.

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

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


Commande rebase

Sometimes you might want to update your patch to include all of the changes in the repository that have happened since you submitted it. This is called "rebasing". There's usually no need to do it, unless the review has been taking a long time and you want to make sure your changes still work with the latest version of the software, or if Gerrit reports a merge conflict in your change.

You can do it locally using the git rebase command with the right options, but Gerrit's web interface provides a more convenient way to do it.

In the simplest scenario, just click "Rebase", keep the default selection of "Rebase on top of the master branch", and click "Rebase" again to confirm.

If your patch has a merge conflict, you will get an error. You can then check the "Allow rebase with conflicts" option and try again, which will amend your patch with conflict markers, similar to those generated by Git commands. You will then need to amend it yourself, editing the files manually to resolve the conflicts.

Sometimes you might also want update your patch to include changes proposed in another patch (adding a dependency on that patch), but which have not been merged yet. In this case, select "Rebase on a specific change, ref, or commit" instead and provide the change in the input field.

If your patch already has such a dependency, you will also get the option to select "Rebase on top of the master branch (breaks relation chain)" in order to remove it. You will also get the option to check "Rebase all ancestors", which will rebase the patch together with the dependency.

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.

Résolution des problèmes

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

Voir aussi

Les pages suivantes sont également utiles :

Guides tiers à propos de Git

Références