Gerrit/guide des messages Commit
Cette page documente un guide de développement de MediaWiki, construit au fil du temps par consensus des développeurs (ou parfois simplement par un des développeurs principaux) |
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.
- 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.
- Utilisez le ton impératif pour décrire la modification que vous apportez. Evitez de décrire les faits, comme "Badge hides zero" ou "Zero in badges" pour indiquer par exemple que les badges sont à zéro; ceci est ambigu et ne décrit pas la modification (est-ce bien ou une erreur ? avant ou après la correction ?). Ecrivez plutôt "Hide zeroes in badges", "Show zeroes in badges", ou "Badge: Restore display of zero" pour indiquer que vous masquez les zéros dans les badges, ou que vous les affichez, ou que vous les restituez parce qu'ils étaient masqués.
Le ton impératif semble indiquer que vous donnez des instructions à quelqu'un et peut commencer par des mots comme « Changer », « Corriger », « Ajouter », « Supprimer », « Documenter » « Refactoriser », « etc. ». - La ligne du sujet doit être courte, dites clairement les modifications apportées par votre validation.
Il est impossible d'utiliser la même ligne de titre pour deux validations concernant des choses différentes. Les utilisateurs liront le titre de votre validation en dehors de son contexte lorsqu'ils le verront passer dans les flux de modifications, les courriels de relecture de code, les journaux de blâme de Git, les notes de version, les journaux des modifications du déploiement, etc. Une ligne de sujet valide permet de décider rapidement si cette validation aura plus d'intérêt qu'une autre pour un sujet ou un problème donné. - Ne terminez pas la ligne du sujet par un point (
.
).
Exemples corrects : | Mauvais exemples : |
---|---|
|
|
Corps
Lorsque vous rédigez votre texte, posez-vous les questions suivantes :
- Pourquoi cette modification devrait-elle ê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 ?
Recommandé :
- Séparez le corps du sujet en intercalant une ligne vide.
- Formatez le message de sorte que les lignes ne dépassent pas 100 caractères. Beaucoup d'éditeur et d'outils peuvent faire cela automatiquement; 72 caractères est la largeur usuelle à laquelle faire le repli.[1] 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 validations en utilisant une valeur (courte) de l'identifiant de modification Gerrit telle que
I83f83377f2
, ou un code de hachage Git tel que51e3fb9a71
. Si la modification correspondante n'a pas encore été fusionnée, utilisez toujours le Change-Id de Gerrit car le code de hachage de la validation Git change une fois la fusion réalisée, ce qui conduirait à une impasse.
Non recommandé :
- Ne faites pas référence aux autres validations avec une URL ou un numéro de modification.
- A la place, utilisez l'identifiant de modification Gerrit tel que
I83f83377f2
, ou le code de hachage Git de la validation tel que51e3fb9a71
. Ce type de hachage est automatiquement converti en un lien permettant d'afficher la modification dans Gerrit, Gitiles et dans les autres navigateurs de dépôt. Ceci vous permet également de naviguer dans le dépôt Git pendant le développement comme viagit show
ou à l'intérieur des éditeurs de texte. - D'un autre côté, une URL ne peut être résolue que dans un navigateur web et permet d'atteindre un emplacement fixe, ce qui casse le flux de travail des relecteurs de code et s'écarte du contexte local. Par exemple, dans un navigateur Git, le hachage vous permet d'aller rapidement d'une validation à la validation liée en restant dans le même outil, au lieu de partir sur Gerrit. Dans Gerrit, vous pouvez aussi chercher le code de hachage pour trouver automatiquement la validation correspondante.
- Un autre problème est que les numéros de modification peuvent être ambigus ou pointer automatiquement vers une validation différente de celle que vous espériez. Ceci est dû au fait que les codes de hachage sont quelques fois simplement des numéros, par exemle la validation 665661 est différente de la modification 665661.
- A la place, utilisez l'identifiant de modification Gerrit tel que
- N'employez pas simplement une URL pour expliquer vos modifications.
- Si les modifications s'appuient sur des discussions données quelque part ou sur une documentation externe, essayez de résumer le ou les points-clés dans votre message de validation et faites également référence à l'URL.
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
.gitmessage
(exemple), utilisez la commande suivante pour obtenir un modèle pour vous guider dans l'écriture d'un message de validation : git config commit.template=.gitmessage
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.
- Gerrit utilise le sujet pour : les notifications par courriel et par IRC, et les résultats de recherche.
- GitHub utilise le sujet pour : l'historique et le sujet du commit.
- Le CLI de Git utilise le sujet pour :
git shortlog
,git log --oneline
,git rebase -i
,git show
, etc. - Notes de diffusion des branches de déploiement Wikimedia de MediaWiki
- et plus encore !
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 :
- Répertoire de classes PHP sous
includes/
ouincludes/libs
, tel que « installer », « jobqueue », « objectcache », « resourceloader », « rdbms », etc. - Nom de classe PHP tel que « Title », « User », « OutputPage », etc. ; typiquement pour les classes sans sous-répertoire dans
includes/
. - Nom de module du chargeur de ressources (ResourceLoader) (tel que « mediawiki.Title », « mediawiki.util », etc.).
- Mot-clé générique affectant différents domaines relatifs au type de modification tels que :
- "build" - pour les modifications des fichiers concernés par le flux de travail du développement, telles que les mises à jour de
package.json
,.travis.yml
, etc. - "tests" or "test" (depending on directory name) - pour les modifications ne concernant que les suites de tests unitaires ou de tests d'intégration, ou les lanceurs de suites de tests.
- "build" - pour les modifications des fichiers concernés par le flux de travail du développement, telles que les mises à jour de
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.[2]
(si vous faites un amend sur un message commit, ajoutez-le immédiatement au-dessus de la ligne Change-Id:
, sans insérer de ligne vide. Rappelez-vous de suivre les règles de structure générales et séparez le corps du sujet par une 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.
Bug: T299087 Bug: T299088
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.
Pour fournir des informations supplémentaires aux développeurs, vous pouvez indiquer la relation inverse en utilisant Needed-By: Iyyy...
dans le dernier paragraphe du message de commit dans l'autre répertoire.
(Iyyy... représente le Change-Id
de votre validation).
Notez que Zuul ne réagit pas à cela; ne sert que pour les lecteurs humains.
Aussi, Gerrit ajoutera automatiquement des liens arrière en fonction de la présence de Depends-On
, quelque soient les Needed-By
.
Créditer d'autres personnes
Co-Authored-by: gerrit_username <gerrit_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.
by
n'est pas mis en majuscules; il s'agit de Co-Authored-by
, et non pas de Co-Authored-By
.
Lectures complémentaires
- Conventions de codage
- commit-message-validator
- Instructions pour le commit Gerrit
- Node.js Instructions pour le Commit
- Instructions pour le Git du noyau
- Instructions pour le commit jQuery
- Instructions pour le commit Erlang
- Une note concernant les messages Git de validation (commit) - par Tim Pope
- Comment écrire un message Git Commit - par Chris Beams
- Gerrit integrations with the Puppet Catalogue Compiler
Références
- ↑ C'est un héritage du temps où les lignes étaient entrées à l'aide de cartes perforées. Les colonnes 1 à 72 contiennent l'instruction et les colonnes 73 à 80, un court commentaire. La taille de 72 colonnes est suffisante pour comprendre le code à vue.
- ↑
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.