Gerrit/guide des messages Commit

From mediawiki.org
Jump to navigation Jump to search
This page is a translated version of the page Gerrit/Commit message guidelines and the translation is 100% complete.
Other languages:

Le message de validation (commit) de vos modifications joue un rôle important. C'est la première chose que les utilisateurs voient de vos modifications.

component: Short subject line

More details. The blank line between the subject and body is
mandatory. The subject line is used to represent the commit in
code-review requests, search results, git rebase, logs, and more.

Bug: T54321

Structure

Sujet

La première ligne du message de validation est connue comme étant le sujet. Le sujet doit avoir une longueur inférieure à 80 caractères (en général 50-70).

  • Résumez vos modifications sur la ligne du sujet. Notez bien que cela restera enregistré dans le dépôt pour toujours.
  • Utilisez le ton impératif pour la ligne du sujet.
    Le ton impératif est celui que vous utiliseriez pour donner des instructions à quelqu'un. Il commence par des mots comme « Changer », « Ajouter », « Supprimer », « Mettre à jour », « Refactoriser » ou « Documenter » par exemple.
    Des exemples corrects sont « Ajouter Badge::query pour interroger l'API » ou « Permettre des zéros dans SimpleBadge::add ».
    De mauvais exemples seraient l'utilisation du participe passé « méthode ajoutée Badge::query » ou « méthode corrigée Badge::query » , ou de formes actives telles que « Badge peut appeler l'API » et « Les zéros sont autorisés pour ajouter des badges ».
  • Le titre de votre validation doit être court, dites clairement ce que vous faites en précisant les modifications que vous apportez. Il est impossible d'utiliser le même titre pour valider des choses différentes. Les utilisateurs se serviront du titre de votre validation lorsqu'ils le verront passer dans les flux de modifications et les journaux de blâme pour savoir s'ils sont intéressés ou perturbés par le changement.
    Exemples corrects : "SimpleBadge: ajouter les textes au survol du formulaire pour les rendre accessibles aux lecteurs d'écrans", "DatabaseFiddler: éviter la boucle infinie quand l'entrée est nulle", ou "Diffs: ajuster les couleurs d'écran pour être conforme avec les nouvelles normes d'architecture d'avril 2020".
    Mauvais exemples : "Implémenter les corrections concernant l'accès", "Ne pas faire planter", ou "Rendre plus joli avec un meilleur agencement".
  • Ne terminez pas la ligne du sujet par un point (.).
  • Eventuellement, préfixez le sujet avec le composant auquel il se rapporte. Le composant représente le domaine général qui sera modifié par votre validation.

Corps

Lorsque vous rédigez votre texte, posez-vous les questions suivantes :

  • Pourquoi cette modification devrait être faite ? Qu'est-ce qui ne va pas avec le code actuel ?
  • Pourquoi de cette manière ? Y a-t-il d'autres moyens ?
  • Avez-vous envisagé d'autres solutions ? Si c'est le cas, expliquez pourquoi elles n'étaient pas aussi concluantes.
  • Comment un relecteur peut-il tester ou vérifier que votre code fonctionne correctement ?

A faire :

  • Séparez le corps du sujet en intercalant une ligne vide.
  • … formatez manuellement le message de sorte que les lignes du titre et du corps ne dépassent pas 100 caractères. Néanmoins ne coupez pas les URLs à la longueur des zones car cela les rendrait non opérationelles; gardez les telles quelles même si elles sont plus longues.
  • … faites référence aux autres commits en utilisant une valeur (courte) de hachage Git, s'ils sont déjà fusionnés. Si les validations ne sont pas encore fusionnées, référencez-les par leur Change-Id Gerrit Change-Id.

Ne faites pas :

  • … référence aux autres validations à l'aide d'une URL Gerrit.
    Remplacez par la valeur de hachage de la validation Git. Ceci permet de de déplacer facilement dans le répertoire Git lorsque vous travaillez hors connexion. Il permet également aux utilisateurs de tous les explorateurs de dépôts (Gerrit, Gitiles, Phabricator, GitHub, et les interfaces Git locaux) de naviguer automatiquement vers les autres commits avec les mêmes interfaces. Une URL ne peut être résolue que lorsque vous êtes connecté et que vous utilisez Gerrit, ce qui empêche les utilisateurs de naviguer rapidement.
  • … l'emploi d'une URL pour expliquer l'ensemble de vos modifications.
    Si les modifications s'appuient sur des discussions données ou sur une documentation externe, décrivez brièvement les points concernés dans le message de validation.

Pied de page et méta données

L'information la plus importante du pied de page est Change-Id (obligatoire) et Bug.

Formatez les métadonnées "Bug" et "Change-Id" exactement comme dans les exemples ci-dessous, et placez les ensemble à la fin du corps, en insérant une ligne vide de séparation.

Voir ci-dessous d'autres informations sur les champs de méta-données individuels.

Exemples

Bon exemple

jquery.badge: Add ability to display the number zero

Cupcake ipsum dolor sit. Amet tart cheesecake tiramisu chocolate cake
topping. Icing ice cream sweet roll. Biscuit dragée toffee wypas. 

Does not yet address T44834 or T176. Follow-up to Id5e7cbb1.

Bug: T42
Change-Id: I88c5f819c42d9fe1468be6b2cf74413d7d6d6907

Mauvais exemple

Improved the code by fixing a bug.

Changed the files a.php and b.php

Bug: T42
Change-Id: I88c5f819c42d9fe1468be6b2cf74413d7d6d6907

Pour plus d'informations

Sujet

La plupart des programmes que nous utilisons et qui affichent le commit de Git, fournissent la ligne du sujet en tant que texte brut. Ce qui signifie que les URLs ne sont pas reconnues, et que la sélection et la copie de texte ne sont souvent pas possibles. C'est pourquoi il ne faut pas référencer les tâches Phabricator, les commit Git, ni les URLs dans la ligne du sujet. Par contre, vous pouvez les placer dans le corps du texte ou dans les métadonnées du pied de page. De cette manière ils seront universellement sélectionnés, copiés, ou cliqués.

Composant

Vous pouvez commencer la ligne du sujet par un composant, ce qui montrera quel domaine du projet est modifié par votre commit.

Il doit être une des valeurs suivantes :

  • Un répertoire de classes PHP sous includes/ ou includes/libs, tel que "installer", "jobqueue", "objectcache", "resourceloader", "rdbms", etc.
  • Un nom de classe PHP tel que "Title", "User", "OutputPage", etc.; typiquement pour les classes qui n'ont pas de sous-répertoire dans includes/.
  • Un nom de module chargeur de ressources ResourceLoader (tel que "mediawiki.Title", "mediawiki.util", etc.).
  • Un mot-clé générique qui affecte différents domaines relatifs au type de modification tels que :
    • "build" - pour les modifications de fichiers concernés par le flux de travail du développement, telles que les mises à jour de package.json, .travis.yml, etc.
    • "tests", "qunit", "phpunit" - pour les modifications qui ne concernent que les suites de tests unitaires ou de tests d'intégration, ou les lanceurs de suites de tests.

Phabricator

Pour faire référence à un bogue ou à une tâche de Phabricator , mentionnez-le en ligne dans le message de commit en utilisant la notation Txxx (par exemple That was caused by T169.)

Pour dire qu'un commit résoud (même partiellement) ou qu'il concerne particulièrement un bogue, ajoutez Bug: Txxx dans le pied de page, à la fin du message de commit.[1] (si vous faites un amend sur un message de commit, insérez-le immédiatement au-dessus de la ligne Change-Id:, sans intercaler aucune ligne vide.)

Bug: T169

Un robot va automatiquement laisser un commentaire sur la tâche Phabricator à propos de tout événement significatif qui est survenu (fusionné, interrompu, etc.). Si un patch corrige un ou plusieurs bogues, placez chaque référence Bug: T12345 sur une ligne séparée, en bas.

Cross-références

A chaque fois que vous faites référence à un autre commit, utilisez le code de hachage SHA-1 de Git, correspondant au commit fusionné. Si le commit est encore en cours de revue de code, utilisez le code de hachage du Change-Id de Gerrit au lieu de celui de Git car le code de hachage est relatif à un ensemble de corrections donné (il est différent lors d'un rebase, ce qui provoquerait un cul de sac).

Change-Id

L'outil git-review de Gerrit va ajouter automatiquement le mot-clé Change-Id: Ixxx aux nouveaux commits.

Dépendances

Depends-Onː Ixxx

Si vous avez des dépendances entre différents dépôts (c'est à dire que votre commit dépend d'un autre commit sur un dépôt qui est différent), déclarez les en ajoutant Depends-On: Ixxx... au dernier paragraphe. (Ixxx... est le Change-Id de l'autre commit.) Ceci indique à Zuul de tester le commit en même temps.

Créditer d'autres personnes

Co-Authored-byː gerrit_username <guerrit_user_email@example.com>

Ajoute cette ligne avant le Change-Id pour créditer les autres développeurs travaillant sur la modification. Vous pouvez en ajouter plusieurs en les séparant à chaque fois avec un passage à la ligne.

Lectures complémentaires

Références

  1. Comme pour tous les entêtes et pieds de page, écrivez séparément le nom avec des mots en majuscules, séparés par des tirets (par exemple Hypothetical-Header-Or-Footer). Faites suivre le nom de deux points (« : »), puis d'un espace. De même que pour le commit Git, les entêtes HTTP et le courriel, le fait d'ajouter des lignes vides supplémentaires au-dessus du pied de page va le séparer et inclure à tord la partie qui précède, dans le corps.