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

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?

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.

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

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.

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

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.

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!

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.