Dois-je utiliser le passé ou le présent dans les messages de commit git ?

Question

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

Voici un engagement récent de John Resig montrant les deux en un seul message :

Ajuster un peu plus les résultats du jeu de jQuery dans les tests de manipulation. J'ai également corrigé l'ordre des résultats attendus des tests.

Est-ce important ? Lequel dois-je utiliser ?

Answer 1

La préférence pour les messages de livraison au présent, de style impératif, vient de Git lui-même. De Documentation/SubmittingPatches dans le repo Git :

Décrivez vos changements d'humeur impératifs, par exemple "make xyzzy do frotz" au lieu de "[Ce patch] fait que xyzzy fait frotz" ou "[J'ai] changé xyzzy pour qu'il fasse frotz", comme si vous donniez des ordres à la base de code pour changer son comportement.

Vous verrez donc beaucoup de messages de commit 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 par souci 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 cela établit de bonnes habitudes qui seront appréciées lorsque vous travaillerez avec d'autres personnes.

Answer 2

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

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

• Écrire au présent dit à quelqu'un ce que fera l'application de l'engagement plutôt que ce que vous avez fait.

C'est la raison la plus correcte d'utiliser le présent, mais uniquement dans le bon style de projet. Cette façon de penser considère tous les commits comme des améliorations ou des fonctionnalités optionnelles, et vous êtes libre de décider quels commits garder et lesquels rejeter dans votre dépôt 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 grand projet s'il est vraiment distribué. En fait, il s'agit probablement soit du noyau Linux, soit de Git. Puisque Linux est probablement ce qui a permis à Git de se répandre et de gagner en popularité, il est facile de comprendre pourquoi les gens considèrent que son style fait autorité. Oui, le style a du sens avec ces deux projets. Ou, en général, il fonctionne avec grand, open source, distribué projets.

Ceci étant dit, la plupart des projets de contrôle de source ne fonctionnent pas comme cela. C'est généralement incorrect pour la plupart des dépôts. C'est une façon moderne de penser aux commits : Les référentiels Subversion (SVN) et CVS pouvaient à peine supporter ce style de check-ins de référentiel. Habituellement, une branche d'intégration se chargeait de filtrer les mauvais check-ins, mais ceux-ci n'étaient généralement pas considérés comme des fonctionnalités "optionnelles" ou "agréables à avoir".

Dans la plupart des scénarios, lorsque vous effectuez des commits sur un dépôt de sources, vous écrivez une entrée de journal qui décrit ce qui a changé avec cette mise à jour, afin qu'il soit plus facile pour les autres dans le futur de comprendre pourquoi un changement a été effectué. Il ne s'agit généralement pas d'un changement facultatif - les autres personnes du projet sont tenues de fusionner ou de rebaser sur ce changement. Vous n'écrivez pas une entrée de journal telle que "Cher journal, aujourd'hui je Rencontrez un garçon et il dit bonjour à moi", mais au lieu de cela vous écrivez "je rencontré un garçon et il a déclaré bonjour à moi."

Enfin, pour ces projets non distribués, 99,99% du temps où une personne lira un message de validation est pour lire l'historique - l'historique est lu au passé. 0,01% du temps, elle décidera si oui ou non elle doit appliquer ce commit ou l'intégrer dans sa branche/référentiel.

• Cohérence. C'est ainsi que cela se passe 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 aussi.

Non, je vous garantis que la majorité des projets jamais enregistrés dans un système de contrôle de version ont eu leur historique au passé (je n'ai pas de références, mais c'est probablement juste, considérant que l'argument du présent est nouveau depuis Git). Les messages de "révision" ou de "commit" au présent n'ont commencé à avoir du sens que dans les projets réellement distribués - voir le premier point ci-dessus.

• Les gens ne lisent pas seulement l'histoire pour savoir "ce qui est arrivé à cette base de code", mais aussi pour répondre à des questions telles que "que se passe-t-il lorsque je sélectionne ce commit", ou "quelles nouvelles choses vont arriver à ma base de code à cause de ces commits que je peux ou ne peux pas fusionner dans le futur".

Voir le premier point. 99,99% du temps où une personne lira un message de validation, c'est pour lire l'histoire - l'histoire se lit au passé. 0.01% du temps, elle décidera si oui ou non elle doit appliquer ce commit ou l'intégrer dans sa branche/référentiel. 99,99% bat 0,01%.

• C'est généralement plus court

Je n'ai jamais vu d'argument valable pour dire qu'il faut utiliser un temps/une grammaire inappropriés parce que c'est plus court. Vous ne gagnerez probablement que 3 caractères en moyenne pour un message standard de 50 caractères. Ceci étant dit, le présent de l'indicatif sera probablement plus court de quelques caractères en moyenne.

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

Les tickets sont rédigés comme quelque chose qui est en train de se produire (par exemple, l'appli montre le mauvais comportement lorsque je clique sur ce bouton), ou quelque chose qui doit être fait à l'avenir (par exemple, le texte aura besoin une critique de l'éditeur).

L'historique (i.e. les messages de commit) est écrit comme quelque chose qui a été fait dans le passé (par exemple le problème était fixe).

Answer 3

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

L'utilisation de l'impératif, du présent est une chose à laquelle il faut s'habituer. s'habituer. Quand j'ai commencé à le mentionner, j'ai rencontré de la résistance. Généralement du style "Le message commit enregistre ce que j'ai fait ". Mais, Git est un système de contrôle de version distribué où il y a potentiellement beaucoup d'endroits d'où obtenir des changements. Plutôt plutôt que d'écrire des messages qui disent ce que vous avez fait ; considérez ces messages comme des instructions pour ce que l'application du commit fera. Plutôt que d'avoir un commit avec le titre :

Renamed the iVars and removed the common prefix.

J'en ai 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. Aussi, si vous regardez l'historique de votre dépôt, vous verrez que les messages générés par Git sont également écrits à ce temps - "Merge" et non "Merged", "Rebase" et non "Rebased". l'écriture au même temps permet de garder une certaine cohérence. Cela semble étrange au début, mais cela mais cela a du sens (témoignages disponibles sur demande) et finit par devenir naturel. et finit par devenir naturel.

Ceci étant dit, il s'agit de votre code, de votre dépôt, alors établissez vos propres vos propres directives et respectez-les.

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

Answer 4

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

• c'est bien d'avoir une norme
• il correspond aux tickets dans le bug tracker qui ont naturellement la forme "implémenter quelque chose", "corriger quelque chose", ou "tester quelque chose".

Answer 5

Pour qui écrivez-vous le message ? Et ce lecteur lit-il généralement le message avant ou après l'engagement lui-même ?

Je pense que de bonnes réponses ont été données ici, des deux points de vue, mais je n'irais pas jusqu'à dire qu'il existe une meilleure réponse pour chaque projet. La division du vote pourrait le suggérer.

c'est-à-dire de résumer :

• Le message s'adresse-t-il principalement à d'autres personnes, généralement lues à un moment donné avant qu'elles n'aient assumé le changement : Une proposition de ce que la prise en charge du changement fera à leur code existant.

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

Peut-être cela mènera-t-il à la motivation de votre équipe/projet, de toute façon.