Comment écrire un bon message Git Commit

Introduction

L'élaboration de messages de validation Git efficaces peut améliorer considérablement la collaboration, la lisibilité du code et la maintenabilité du projet pendant des années. Pourtant, cet aspect est souvent négligé ou traité après coup dans le processus de développement. Dans cet article de blog, je vais aller droit au but et présenter les principes clés de la rédaction de messages de validation Git exceptionnels que tout développeur devrait suivre !

1. Commencez par un verbe à l'impératif en majuscule dans la ligne de l'objet.

Un message de livraison doit indiquer clairement ce que fait cette livraison. Pour faciliter la lecture et la maintenance, utilisez un verbe impératif en majuscule au début du message.

Exemple

• Ajouter nouvelle fonctionnalité pour la connexion des utilisateurs

• Correction bug dans le traitement des paiements

• Mise à jour documentation pour les points d'extrémité de l'API

2. Concision de l'objet du message

Votre message de validation doit être suffisamment descriptif pour transmettre l'objectif de la validation, mais suffisamment concis pour être lu rapidement. La ligne d'objet doit comporter environ 50 caractères et le corps du message doit contenir des détails supplémentaires.

• Bon message d'engagement : Refonte du module d'authentification des utilisateurs

• Mauvais message de validation : Refonte du module d'authentification des utilisateurs pour améliorer les performances et la lisibilité.

3. Séparer le résumé du corps du texte par une ligne blanche

Si votre message de validation doit être plus détaillé, ajoutez un corps. Veillez à ajouter une ligne vide entre le résumé et le corps du message pour le rendre plus lisible.

Ajouter une mise en cache locale pour améliorer les performances de l'application

Cette modification met en œuvre un mécanisme de mise en cache local afin de réduire la charge de la base de données et d'améliorer les temps de réponse globaux sur le réseau.
et d'améliorer les temps de réponse globaux sur le réseau. Le cache est invalidé toutes les dix minutes pour garantir la fraîcheur des données.

4. Utiliser l'humeur impérative

En gardant à l'esprit la convention standard, écrivez les messages de validation dans l'humeur impérative, un temps typiquement associé aux commandes et aux actions. Il s'agit de donner des instructions sur ce qui est fait au moment de l'application de la livraison.

Exemples :

• Corriger : Ajouter l'authentification de l'utilisateur

• Incorrect : Ajout d'une l'authentification de l'utilisateur

• Corriger : Fixer authentification de l'utilisateur

• Incorrect : Corrigé authentification de l'utilisateur

• Corriger : Mettre à jour l'authentification de l'utilisateur

• Incorrect : Mise à jour authentification de l'utilisateur

5. Expliquer le "quoi" et le "pourquoi" du corps

Utilisez le corps du texte pour donner plus de détails sur le changement : expliquez ce qui a été fait et pourquoi cela a été fait. Il est ainsi plus facile pour les autres - et pour vous-même à l'avenir - de comprendre le contexte et la raison de la modification :

• Ce que: Refonte de la logique d'authentification

• Pourquoi: Améliorer les performances et réduire la duplication du code

Exemple :

Refonte de la logique d'authentification

La logique d'authentification a été extraite d'une classe et placée dans un module distinct afin d'améliorer les performances et de réduire la duplication du code. Ce changement
facilitera également la mise en œuvre des améliorations futures.

6. Utiliser des puces pour les listes

Si le commit comprend plusieurs changements, listez-les sous forme de puces. Cela facilite la lecture et la compréhension de chaque changement :

Améliorer la gestion des erreurs dans le traitement des paiements

- Ajout d'une validation pour les champs de saisie des paiements
- Traitement des erreurs de l'API avec un mécanisme de réessai
- Enregistrement de messages d'erreur détaillés pour le débogage

7. Référence aux questions ou aux billets pertinents

Si votre livraison résout ou est liée à un problème ou une tâche spécifique, faites-y référence dans votre système de gestion de projet - par exemple, GitHub Issues, Jira. Cela permet de maintenir l'état des problèmes à jour, et le contexte sera très utile aux lecteurs par la suite.

Correction du calcul incorrect du total (#4342)

Correction de la logique de calcul des totaux de commande, en s'assurant que les taxes et les réductions sont appliquées.
que les taxes et les remises sont appliquées.

8. Examen et révision

Avant de valider votre message et de l'envoyer dans le référentiel, prenez le temps de le relire. Vérifiez les fautes d'orthographe et de grammaire, ainsi que la clarté du message. Un message de validation bien rédigé reflète le professionnalisme et l'attention portée aux détails, ce qui peut faire gagner du temps et éviter des maux de tête en aval.

Liste de contrôle rapide

• Majuscules : Avez-vous commencé votre objet par une majuscule ?

• Concision : Votre ligne d'objet comporte-t-elle 50 caractères ou moins ?

• Ligne blanche : Avez-vous ajouté une ligne vierge après le résumé s'il y a un corps ?

• L'humeur impérative : Le message est-il à l'impératif ?

• Détail : Le corps (s'il est présent) explique-t-il le quoi, le pourquoi et le comment ?

• Listes : Avez-vous utilisé des puces pour votre liste ?

• Références : Avez-vous fait référence à des questions ou à des PR pertinents ?

• Relecture : Avez-vous vérifié la clarté et les fautes de frappe ?

Conclusion

La rédaction de messages de validation Git de qualité améliore la collaboration et la maintenabilité du projet. En suivant ces quelques conseils simples - utiliser des verbes impératifs, rester concis, expliquer le "quoi" et le "pourquoi", et faire référence aux problèmes pertinents - vous créerez un historique de projet précieux, facile à parcourir et à comprendre. Nous avons également publié un autre article intitulé "3 raisons pour lesquelles vous devriez utiliser les Commits conventionnels" si vous souhaitez en savoir plus.

Nous aimerions également que vous vous joigniez à nous sur le Communauté Vonage Slack ou envoyez-nous un message sur X et nous vous répondrons. Merci encore d'avoir lu, et je vous retrouverai dans le prochain numéro !

Bon engagement !