Dois-je utiliser le temps passé ou présent dans les messages de validation git? [fermé]


531

J'ai lu une fois que les messages git commit devraient être au présent impératif, par exemple "Ajouter des tests pour x". Je me retrouve toujours à utiliser le passé, par exemple "Ajout de tests pour x", ce qui me semble beaucoup plus naturel.

Voici un récent commit de John Resig montrant le message deux en un:

Ajustez d'autres résultats de l'ensemble jQuery dans les tests de manipulation. Correction également de l'ordre des résultats de test attendus.

Est-ce que ça importe? Que dois-je utiliser?


12
Cette question doit donc être classée comme étant principalement basée sur l'opinion . Regardez déjà les différences d'opinion entre impératif et passé ! Cela étant dit, je vote pour le temps impératif, car cela aide vraiment à clarifier ce que vous faites lors de la réécriture de votre histoire, de la sélection des cerises, de l'application de correctifs, etc.!




3
@Eonil s'il est fermé pour être basé sur l'opinion ici, il sera également fermé pour être basé sur l'opinion.
ratchet freak

Réponses:


601

La préférence pour les messages de commit de style impératif au présent vient de Git lui-même. Depuis Documentation / SubmittingPatches dans le dépôt Git:

Décrivez vos changements d'humeur impérative, par exemple, "faites xyzzy faire frotz" au lieu de "[Ce patch] fait xyzzy faire frotz" ou "[j'ai] changé xyzzy pour faire frotz", comme si vous donniez des ordres à la base de code pour changer son comportement.

Vous verrez donc beaucoup de messages de validation Git écrits dans ce style. Si vous travaillez en équipe ou sur un logiciel open source, il est utile que tout le monde s'en tienne à ce style pour plus de cohérence. Même si vous travaillez sur un projet privé, et que vous êtes le seul à voir votre historique Git, il est utile d'utiliser l'humeur impérative car elle établit de bonnes habitudes qui seront appréciées lorsque vous travaillez avec d'autres.


90
Je pense que c'est un excellent choix. Pensez à ce qu'est un commit, sous forme de diff: un ensemble d'instructions sur la façon de passer d'un état précédent à un nouvel état. Tout comme le diff dit "ajoutez cette ligne ici, supprimez cette ligne ici", le message de validation dit en termes qualitatifs "faites ce changement". (Oui, git stocke le commit simplement comme un arbre avec des métadonnées, mais pour un humain, la partie importante d'un commit est le diff.)
Cascabel

124
Vous pouvez voir un commit comme un ensemble d'instructions sur la façon de passer de l'état précédent au nouvel état; mais je le vois plus comme un point de contrôle dans l'évolution du code. Pour moi, le message de validation est un journal de ce qui a été fait pour le code depuis la validation précédente; et pour un journal, le passé a beaucoup plus de sens. Si vous pensez vraiment que le message de validation doit être un ensemble d'instructions, alors le temps impératif est le chemin à parcourir. Je n'y pense vraiment pas de cette façon.
karadoc

10
@oschrenk: Les versions ultérieures du fichier ont donné une raison: "Décrivez vos changements d'humeur impérative, par exemple," faites xyzzy faire frotz "au lieu de" [ce patch] fait xyzzy faire frotz "ou" [j'ai] changé xyzzy pour faire frotz ", comme si vous donniez l'ordre à la base de code de modifier son comportement."
mipadi

44
Le message de validation doit être impératif, au présent, car avec git vous ou quelqu'un d'autre peut finir par faire rebaseou, cherry-picket dans ce cas, la validation peut être utilisée en dehors de son contexte d'origine. Par conséquent, le message de validation doit être écrit de manière autonome sans attendre du lecteur qu'il affiche les messages de validation environnants. Lorsque vous choisissez des correctifs, il est plus judicieux d'appliquer "Corriger l'algorithme de tri rapide" ou "Tri: améliorer les performances" au lieu de "Bogue fixe # 124" ou "Tri modifié pour améliorer les performances".
Mikko Rantalainen

5
La façon dont je pense à ce sujet est que le message devrait me dire ce qui va changer si je choisis d'appliquer ce commit à ma branche. Je ne le considère pas comme un journal mais comme des états vers lesquels je peux passer et j'ai besoin de savoir ce qui se passera lorsque je choisirai un état particulier.
steinybot

357

Votre projet doit presque toujours utiliser le passé . Dans tous les cas, le projet doit toujours utiliser le même temps pour la cohérence et la clarté.

Je comprends certains des autres arguments faisant valoir l'utilisation du présent, mais ils ne s'appliquent généralement pas. Les points suivants sont des arguments courants pour écrire au présent et ma réponse.

  • Écrire au présent indique à quelqu'un ce que l'application du commit fera , plutôt que ce que vous avez fait.

C'est la raison la plus correcte pour utiliser le temps présent, mais uniquement avec le bon style de projet. Cette manière de penser considère toutes les validations comme des améliorations ou fonctionnalités facultatives, et vous êtes libre de décider quelles validations conserver et lesquelles rejeter dans votre référentiel particulier.

Cet argument fonctionne si vous avez affaire à un projet véritablement distribué. Si vous avez affaire à un projet distribué, vous travaillez probablement sur un projet open source. Et c'est probablement un très gros projet s'il est vraiment distribué. En fait, c'est probablement le noyau Linux ou Git. Étant donné que Linux est probablement la cause de la propagation et de la popularité de Git, il est facile de comprendre pourquoi les gens considéreraient son style comme l'autorité. Oui, le style a du sens avec ces deux projets. Ou, en général, il fonctionne avec de grands projets distribués open source .

Cela étant dit, la plupart des projets de contrôle de code source ne fonctionnent pas comme ça. Il est généralement incorrect pour la plupart des référentiels. C'est une façon moderne de penser aux commits: les référentiels Subversion (SVN) et CVS pourraient à peine supporter ce style d'archivage de référentiel. Habituellement, une branche d'intégration traitait le filtrage des mauvais enregistrements, mais ceux-ci n'étaient généralement pas considérés comme «facultatifs» ou «fonctionnalités intéressantes».

Dans la plupart des scénarios, lorsque vous effectuez des validations dans un référentiel source, vous écrivez une entrée de journal qui décrit ce qui a changé avec cette mise à jour, pour permettre aux autres utilisateurs de comprendre pourquoi une modification a été effectuée. Ce n'est généralement pas un changement facultatif - d'autres personnes dans le projet doivent fusionner ou rebaser dessus. Vous n'écrivez pas un journal tel que "Cher journal, aujourd'hui je rencontre un garçon et il me dit bonjour.", Mais à la place vous écrivez "J'ai rencontré un garçon et il m'a dit bonjour".

Enfin, pour de tels projets non distribués, 99,99% du temps, une personne lira un message de validation pour lire l'historique - l'histoire est lue au passé. 0,01% du temps, il décidera s'ils doivent appliquer ce commit ou l'intégrer dans leur branche / référentiel.

  • Cohérence. C'est comme ça dans de nombreux projets (y compris git lui-même). Les outils git qui génèrent des commits (comme git merge ou git revert) le font également.

Non, je vous garantis que la majorité des projets jamais connectés dans un système de contrôle de version ont eu leur histoire au passé (je n'ai pas de références, mais c'est probablement vrai, étant donné que l'argument du temps présent est nouveau depuis Git). Les messages de «révision» ou de validation au présent n'ont commencé à avoir un sens que dans les projets vraiment distribués - voir le premier point ci-dessus.

  • Les gens lisent non seulement l'historique pour savoir «ce qui est arrivé à cette base de code», mais aussi pour répondre à des questions comme «ce qui se passe quand je sélectionne ce commit», ou «quel genre de nouvelles choses vont arriver à ma base de code à cause de ces commits Je pourrai ou non fusionner à l'avenir ".

Voir le premier point. 99,99% du temps, une personne lira un message de validation pour lire l'historique - l'histoire est lue au passé. 0,01% du temps, il décidera s'ils doivent appliquer ce commit ou l'intégrer dans leur branche / référentiel. 99,99% bat 0,01%.

  • C'est généralement plus court

Je n'ai jamais vu un bon argument qui dit utiliser un mauvais temps / grammaire parce qu'il est plus court. Vous n'enregistrerez probablement que 3 caractères en moyenne pour un message standard de 50 caractères. Cela étant dit, le temps présent en moyenne sera probablement de quelques caractères plus court.

  • Vous pouvez nommer les validations de manière plus cohérente avec les titres des tickets dans votre tracker de problème / fonctionnalité (qui n'utilisent pas le passé, bien que parfois futur)

Les tickets sont écrits soit comme quelque chose qui se passe actuellement (par exemple, l'application affiche un mauvais comportement lorsque je clique sur ce bouton), soit comme quelque chose qui doit être fait à l'avenir (par exemple, le texte devra être révisé par l'éditeur).

L'historique (c'est-à-dire les messages de validation) est écrit comme quelque chose qui a été fait dans le passé (par exemple, le problème a été résolu).


79
J'ai entendu pour la première fois aujourd'hui la préférence supposée pour les commits de style impératif. Pour moi, cela sonnait si peu naturel et bizarre que j'ai décidé de demander plus d'opinions. Je suis heureux de voir que je ne suis pas le seul à penser que le passé est plus naturel pour les messages de validation. :)
Karadoc

57
Les messages de validation de fusion et de rebase générés automatiquement par git sont impératifs et au temps présent ("Fusionner", pas "Fusionné"; "Rebaser", pas "Rebasé"), vous pouvez donc faire correspondre cela dans vos propres messages de validation par souci de cohérence.
mjs

13
Il semble que la différence se situe entre l'accent mis sur la modification du logiciel - "Correction de X en faisant Y" - ou le référentiel - "Faire Y pour corriger X". +1 pour un bon argument, mais je pense que le dépôt devrait généralement se concentrer sur lui-même plutôt que sur le logiciel résultant.
l0b0

28
Le fait est que, en utilisant des travaux impératifs et actuels pour des projets énormes (par exemple Linux), il évolue évidemment. De plus, il ne nécessite pratiquement aucun effort en utilisant le passé. En conséquence, je ne vois aucune raison (autre que "les personnes âgées sont utilisées pour écrire des messages de validation au passé") d'utiliser autre chose que le présent impératif. Si vous pouvez apprendre le jeu de commandes git, vous pouvez apprendre à écrire au présent impératif.
Mikko Rantalainen

35
L'impératif n'est pas "nouveau depuis git". ChangeLog existait bien avant git, et l'utilisation de l'impératif a toujours été le style recommandé dans le projet GNU. gnu.org/prep/standards/html_node/Style-of-Change-Logs.html
adl

81

J'ai écrit une description plus complète sur 365git .

L'utilisation de l'impératif, du présent, est celle qui prend un peu de temps pour s'y habituer. Quand j'ai commencé à le mentionner, il a rencontré une résistance. Généralement sur le modèle de «Le message de validation enregistre ce que j'ai fait». Mais, Git est un système de contrôle de version distribué où il existe potentiellement de nombreux endroits pour obtenir des modifications. Plutôt que d'écrire des messages qui disent ce que vous avez fait; considérez ces messages comme les instructions pour ce que l'application de la validation fera. Plutôt que d'avoir un commit avec le titre:

Renamed the iVars and removed the common prefix.

En avoir un comme ça:

Rename the iVars to remove the common prefix

Ce qui indique à quelqu'un ce que l'application du commit fera, plutôt que ce que vous avez fait. De plus, si vous regardez l'historique de votre référentiel, vous verrez que les messages générés par Git sont également écrits dans ce temps - «Fusionner» et non «Fusionné», «Rebaser» et non «Rebasé», donc écrire au même temps permet de garder les choses cohérentes. Cela semble étrange au début, mais cela a du sens (témoignages disponibles sur demande) et devient finalement naturel.

Cela dit, c'est votre code, votre référentiel: alors définissez vos propres directives et respectez-les.

Si, toutefois, vous décidez de suivre cette voie, git rebase -il'option de reformulation serait une bonne chose à examiner.


7
Eh bien, vous avez mélangé deux directives différentes: le projet open source Git et l'utilisation régulière de Git. Le lien fourni ne mentionne pas du tout le temps . Le document officiel Git ne mentionne que la limite de 50 caractères. Git est un VCS distribué où il existe de nombreux endroits pour obtenir des modifications ... considérez ces messages comme les instructions pour ce que l'application du commit fera. Cela ne s'applique qu'à quelques projets qui sont en réalité des projets distribués. 99,999% des validations Git ne seront jamais appliquées manuellement de cette manière. Dans la plupart des projets, l'historique est un journal des modifications, qui devrait être au passé.
Matt Quigley

4
"et devrait sauter le point
final

30

Tenez-vous à l'impératif présent, car

  • c'est bon d'avoir un standard
  • il correspond aux tickets dans le suivi des bogues qui ont naturellement la forme «implémenter quelque chose», «réparer quelque chose» ou «tester quelque chose».

16

Pour qui écrivez-vous le message? Et est-ce que le lecteur lit généralement le message avant ou après la prise de possession par lui-même?

Je pense que de bonnes réponses ont été données des deux points de vue, je serais peut-être simplement loin de suggérer qu'il existe une meilleure réponse pour chaque projet. Le vote par division pourrait suggérer autant.

c'est-à-dire résumer:

  • Le message est-il principalement destiné à d'autres personnes, lisant généralement à un moment donné avant qu'elles aient assumé le changement: une proposition de ce que la modification apportera à leur code existant.

  • Le message est-il principalement sous forme de journal / enregistrement pour vous-même (ou pour votre équipe), mais généralement lu dans la perspective d'avoir assumé le changement et de chercher en arrière pour découvrir ce qui s'est passé.

Peut-être que cela entraînera la motivation de votre équipe / projet, de toute façon.


10

Est-ce que ça importe? les gens sont généralement assez intelligents pour interpréter correctement les messages, sinon, vous ne devriez probablement pas les laisser accéder à votre référentiel de toute façon!


27
Pour certaines personnes , des choses comme ça comptent beaucoup.
Wesley Murch

2
@mog le lien ne fait aucune déclaration sur le présent et le passé.
ceving

2
Si le projet évolue à grande échelle, les personnes effectuant la révision de code et la recherche de bogues verront tellement de commits qu'ils ont besoin de toute l'aide que vous et moi pouvons vous fournir. Il ne sert à rien d'économiser quelques secondes maintenant pour causer des maux de tête majeurs à l'avenir pour ne pas écrire un bon message de validation.
Mikko Rantalainen

Je ne dis pas de ne pas écrire un bon message de validation. Je dis que peu importe si vous utilisez le passé ou le présent.
Michael Baldry,

1
Comment sauriez-vous que la personne qui n'est pas en mesure d'interpréter votre message de validation est la cause de cette personne qui n'est pas assez capable ou que vous n'êtes pas assez capable d'écrire un bon message de validation?
Haris

7

C'est comme tu veux. Utilisez simplement le message de validation comme vous le souhaitez. Mais c'est plus facile si vous ne basculez pas entre les heures et les langues.

Et si vous vous développez en équipe - cela devrait être discuté et réglé de manière fixe.

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.