Devrais-je utiliser le passé ou le présent dans les messages git commit?
I lu une fois que les messages de git commit doivent être au présent impératif, par ex. "Ajouter des tests pour x". Je me retrouve toujours à utiliser le passé, par exemple "Ajout de tests pour x" cependant, ce qui me semble beaucoup plus naturel.
Voici un commit récent de John Resig montrant le message deux en un:
Ajustez encore plus de résultats d'ensemble jQuery dans les tests de manipulation. Également corrigé l'ordre des résultats de test attendus.
Est-ce que ça importe? Que devrais-je utiliser?
La préférence pour les messages de validation au style présent et impératif vient de Git lui-même. Depuis Documentation/SubmittingPatches dans le référentiel Git:
Décrivez vos changements d'humeur impérative, par exemple "make xyzzy do frotz" au lieu de "[Ce patch] rend xyzzy do frotz" ou "[I] a modifié xyzzy pour le faire 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 des logiciels open source, il est utile que tout le monde respecte ce style par souci de cohérence. Même si vous travaillez sur un projet privé et que vous êtes le seul à pouvoir consulter l'historique de votre git, il est utile d'utiliser l'ambiance impérative, car elle établit de bonnes habitudes qui seront appréciées lorsque vous travaillerez 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 plaidant en faveur de l’utilisation du présent, mais ils ne sont généralement pas . Les points suivants sont des arguments courants pour écrire au présent, ainsi que ma réponse.
- Ecrire au présent indique à quelqu'un ce que fera l'application commit , plutôt que ce que vous avez fait.
C'est la raison la plus correcte de vouloir utiliser le présent, mais uniquement avec le bon style de projet. Cette façon de penser considère tous les commits comme des améliorations ou des fonctionnalités facultatives, et vous êtes libre de choisir ceux qui doivent être conservés et ceux qui doivent être rejetés dans votre référentiel particulier.
Cet argument fonctionne si vous traitez avec un projet vraiment distribué. Si vous traitez avec 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, il s’agit probablement du noyau Linux ou de Git. Étant donné que Linux est probablement ce qui a poussé Git à se répandre et à gagner en popularité, il est facile de comprendre pourquoi les gens considèrent son style comme une autorité. Oui, le style a du sens avec ces deux projets. Ou, en général, cela fonctionne avec grands projets open source, distribués .
Cela étant dit, la plupart des projets sous contrôle de code source ne fonctionnent pas de la sorte. Il est généralement incorrect pour la plupart des référentiels. C'est une façon moderne de penser à un commet: les référentiels Subversion (SVN) et CVS pourraient à peine supporter ce type d'archivage de référentiel. Habituellement, une branche d’intégration gère le filtrage des enregistrements incorrects, mais ceux-ci ne sont généralement pas considérés comme des fonctionnalités "facultatives" ou "agréables à avoir".
Dans la plupart des scénarios, lorsque vous effectuez des validations dans un référentiel source, vous écrivez une entrée de journal décrivant ce qui a changé avec cette mise à jour, afin que les autres puissent plus facilement comprendre pourquoi une modification a été apportée. Ce n'est généralement pas un changement facultatif - il est nécessaire que d'autres personnes du projet fusionnent ou rebasonnent dessus. Vous n'écrivez pas une entrée de journal telle que "Cher journal, aujourd'hui je rencontre un garçon et il dit bonjour à moi. ", mais vous écrivez à la place" j'ai rencontré un garçon et il a dit bonjour à moi. "
Enfin, pour de tels projets non distribués, 99,99% du temps, une personne lira un message de validation est destiné à la lecture de l'historique - l'historique est lu au passé. 0,01% du temps, ce sera à eux-mêmes de décider d'appliquer ou non ce commit ou de l'intégrer dans leur branche/référentiel.
- Cohérence. C'est comme ça dans de nombreux projets (y compris git). 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 enregistrés dans un système de contrôle de version ont eu une 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 ne commencent à se comprendre que dans des projets vraiment distribués - voir le premier point ci-dessus.
- Les gens lisent non seulement l'histoire pour savoir "ce qu'il est advenu de 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 Je peux ou ne peux pas fusionner dans le futur ".
Voir le premier point. 99,99% du temps, une personne lira un message de validation est destiné à la lecture de l'historique - l'historique est lu au passé. 0,01% du temps, ce sera à eux-mêmes de décider d'appliquer ou non ce commit ou de l'intégrer dans leur branche/référentiel. 99,99% bat 0,01%.
- C'est habituellement plus court
Je n'ai jamais vu de bon argument disant d'utiliser un syntaxe/un langage inapproprié, car il est plus court. Vous ne sauvegarderez 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 plus court de quelques caractères.
- Vous pouvez nommer les commits de manière plus cohérente avec les titres des tickets dans votre suivi de problème/fonctionnalité (qui n'utilise pas le passé, bien que parfois plus tard)
Les billets sont écrits soit comme quelque chose qui se passe actuellement (par exemple, l'application montre le mauvais comportement lorsque je clique sur ce bouton), ou quelque chose qui doit être fait à l'avenir (par exemple, le texte nécessitera une révision par l'éditeur).
L’historique (c’est-à-dire les messages de validation) s’écrit comme si quelque chose avait été fait dans le passé (par exemple, le problème était résolu).
J'ai écrit une description plus complète sur 65git .
L’utilisation de l’impératif, du présent est un exercice qui demande un peu d’habitude. Quand j'ai commencé à en parler, il a rencontré une résistance. Généralement, le long de la ligne “Le message de validation enregistre ce que j'ai fait”. Cependant, Git est un système de contrôle de version distribué sur lequel il existe potentiellement de nombreux emplacements pour obtenir des modifications. Plutôt que d’écrire des messages qui disent ce que vous avez fait; Considérez ces messages comme des instructions expliquant ce que fera l'application commit. 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 prefixCe qui indique à quelqu'un ce que fera l'application commit, plutôt que ce que vous avez fait. En outre, si vous examinez l'historique de votre référentiel, vous verrez que les messages générés par Git sont également écrits à ce temps - "Fusionner" et non "Fusionné", "Rebase", pas "Rebondu". Cela semble étrange au début, mais cela a du sens (des témoignages sont disponibles sur demande) et finit par devenir naturel.
Cela dit, c’est votre code, votre référentiel: configurez donc vos propres directives et respectez-les.
Si, toutefois, vous décidez de suivre cette voie, alors
git rebase -iavec l'option de reformulation serait une bonne chose à examiner.
S'en tenir à l'impératif présent car
- c'est bien d'avoir un standard
- il fait correspondre les tickets dans le gestionnaire de 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 ce lecteur lit-il généralement le message avant ou après l’acquisition de la propriété?
Je pense que de bonnes réponses ont été données des deux points de vue. Je ne dirais peut-être pas que chaque projet est la meilleure. Le vote par division pourrait suggérer autant.
c'est-à-dire à résumer:
Le message s’adresse-t-il principalement aux autres personnes, lisant généralement à un moment donné avant d’avoir pris en charge le changement: Une proposition indiquant ce que le changement apportera fera à 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 comme lire du point de vue de la prise en charge du changement et de la recherche en arrière pour découvrir ce qui s'est passé.
Peut-être que cela stimulera la motivation de votre équipe/projet.
est-ce que ça importe? les gens sont généralement assez intelligents pour interpréter correctement les messages; s'ils ne le sont pas, 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 il est plus facile de ne pas basculer entre les époques et les langues.
Et si vous développez en équipe, cela doit être discuté et réglé.