Bonnes pratiques pour les messages de validation

Imaginez que vous consultiez l’historique de votre projet. Sans messages de validation clairs, ce serait comme lire un journal intime rempli de pages vierges !

De bons messages de validation sont essentiels pour comprendre pourquoi les modifications ont été effectuées, ce qui a été modifié et comment ces changements influencent le projet. Cela vous aide, vous et votre équipe, à rechercher les erreurs, à relire le code et à intégrer les nouveaux membres.

Un message de validation Git standard comporte deux parties principales :

• Ligne d’objet : une ligne unique et concise qui résume la modification.
• Corps (facultatif) : une explication plus détaillée, séparée de l’objet par une ligne vide.

Voyez-le comme un e-mail : une ligne d’objet pour une lecture rapide et un corps pour les détails.

La ligne d’objet est la partie la plus importante. Voici les règles à respecter :

• Concision : limitez-la à 50 à 72 caractères.
• Mode impératif : commencez par un verbe au présent, par exemple « Ajouter une fonctionnalité », et non « Fonctionnalité ajoutée » ou « Ajout d’une fonctionnalité ».
• Première lettre en majuscule : c’est la pratique habituelle pour faciliter la lecture.
• Pas de point : ne terminez pas la ligne d’objet par un point.

Observons quelques lignes d’objet bonnes et mauvaises :

• Bonne : Fix: broken login button
• Bonne : Feat: implement user profile page
• Mauvaise : Fixed a bug in the login system that was causing issues. (trop longue, au passé)
• Mauvaise : updates (trop vague)

Visez la clarté et la concision !

Le corps de la validation vous permet d’expliquer la motivation de la modification, son contexte et les détails qui ne sont pas évidents à partir du code seul.

Utilisez-le lorsque votre modification nécessite davantage d’explications que ne peut en fournir la ligne d’objet. Limitez les lignes à environ 72 caractères pour améliorer la lisibilité dans les outils Git.

Lorsque vous rédigez le corps :

• Expliquez pourquoi la modification a été effectuée, et pas seulement ce qui a été modifié.
• Décrivez les compromis et les décisions de conception.
• Mentionnez les effets secondaires potentiels ou les points à surveiller.
• Laissez une ligne vide entre l’objet et le corps.

Cela fournit un contexte précieux aux personnes qui liront le message ultérieurement.

Voici à quoi pourrait ressembler un message de validation complet et bien structuré :

De nombreuses équipes adoptent une convention selon laquelle la ligne d’objet commence par un préfixe de type. Cela permet de catégoriser rapidement les modifications.

Les préfixes courants comprennent :

• feat: (nouvelle fonctionnalité)
• fix: (correction d’un bogue)
• docs: (modification de la documentation)
• style: (style du code, sans modification fonctionnelle)
• refactor: (remaniement du code)
• test: (ajout de tests)
• chore: (maintenance, modifications du processus de compilation)

Il est recommandé de lier vos validations aux problèmes ou demandes de fusion associés dans votre système de gestion de projet, par exemple GitHub Issues ou Jira.

Pour cela, incluez dans votre message de validation, généralement dans le corps, des expressions telles que Closes #123, Fixes #45 ou Refs #67. Vos modifications de code seront ainsi automatiquement associées à la tâche suivie.

Selon les bonnes pratiques, lesquelles des caractéristiques suivantes correspondent à un message de validation Git bien rédigé ?

Vous avez appris que des messages de validation bien rédigés sont essentiels à la clarté d’un projet et à la collaboration. En suivant ces bonnes pratiques, vous faites de l’historique de votre projet une ressource précieuse !

• Rédigez des lignes d’objet concises et au mode impératif.
• Utilisez le corps pour expliquer « pourquoi » une modification a été effectuée.
• Envisagez des préfixes de type pour catégoriser les modifications.
• Ajoutez des liens vers les problèmes ou les demandes de fusion pour fournir du contexte.

Bonnes validations !