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



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
Follow Installing Git to learn how to install git on your operating system.



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



Générer une nouvelle clé SSH
Follow SSH keys.



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

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



Un exemple de message de connexion SSH Gerrit réussie ressemble à ceci :
 * 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 (remplacez  par votre nom d'utilisateur). Le   va fournir une sortie verbeuse pour aider à résoudre les problèmes. Ensuite lisez les résolutions des problèmes Gerrit.



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

Existing repositories
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
If you have downloaded MediaWiki or extensions using Vagrant, make sure you have configured Git to push code using SSH instead of HTTPS.



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.

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.

Font Awesome 5 brands linux.svg Linux

 * Utilisez l'outil graphique de gestion des paquets logiciels de votre distribution Linux pour installer le package.
 * Si git-review ne figure as dans votre distribution, allez sur git-review pour voir d'autres possibilités telles que l'installation de git-review en utilisant l'installateur Python de paquets 'pip'.
 * 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 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 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
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 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 :

Notez néanmoins que certains dépôts utilisent un noms différent pour leur branche principale de développement (par exemple  au lieu de , ou le dépôt   a une branche   au lieu de  ).



Créer une branche
Créez d'abord une branche locale pour votre nouvelle modification. Remplacez ci-dessous par un nom court et suffisamment descriptif (par exemple   si une tâche  correspondante existe pour vos modifications, , ou  ). 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 :

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  ) pour la validation prochaine.

<span id="Stage_your_changes_for_a_commit">

Réserver les modifications avant de valider
Exécuter 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  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, donc la commande sera :

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

<span id="Commit_your_staged_changes">

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

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

<span id="Prepare_to_push_your_commit_to_Gerrit">

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.

<span id="Push_your_commit_to_Gerrit">

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!

If git review -R fails
If you are asked to enter your git credentials (a username and password) after running and it responds that they are invalid, it's likely that the repo was cloned using https and not ssh. You should not recieve any prompt to enter credentials if you are using ssh. To switch the repo to ssh, run and replace  with the one found in gitiles that begins with. Make sure to add your Gerrit username before. For example, the repository URL for the Echo repository would be.

If you get a, re-follow the instructions at  to make sure your ssh agent is running and your identity is added. If you close your Git Bash shell, you will be signed out and need to re-follow these instructions each time.

<span id="View_the_Change_/_Next_Steps">

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.

<span id="Other_common_situations">

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

<span id="Squash_several_commits_into_one_single_commit_via_rebase">

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

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

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

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 :

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

<span id="Amending_a_change_(your_own_or_someone_else&#039;s)">

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

Commande rebase
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 :  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é ! )

Par exemple :

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

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 :

Par exemple :

<span id="Make_changes_and_push">

Faites vos modifications puis push
Ensuite, faites quelques modifications avec votre éditeur de texte favori.

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

Validez la modification :

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

<span id="Push_to_a_branch_different_than_master">

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.

Résolution des problèmes
Pour les problèmes et la manière de les résoudre, voir.

<span id="See_also">

Voir aussi
Les pages suivantes sont également utiles :


 * Tutoriel abrégé de Gerrit
 * Tutoriel Gerrit TortoiseGit
 * Téléversement des corrections Wikimedia dans Gerrit
 * Tutoriel abrégé de Gerrit
 * Tutoriel Gerrit TortoiseGit
 * Téléversement des corrections Wikimedia dans Gerrit