Rédiger d'excellents messages de commit Git : bonnes pratiques pour un historique clair

Les messages de commit Git sont les notes sur lesquelles votre équipe compte lorsque le code se casse, que le comportement change ou qu'une version doit être expliquée. Un message clair vous indique ce qui a changé et pourquoi, sans vous obliger à rétro-ingénierer le diff.

Les bons messages de commit n'ont pas besoin d'être sophistiqués. Ils nécessitent une ligne d'objet utile, suffisamment de contexte pour les modifications non triviales et un style cohérent que votre équipe pourra lire des mois plus tard.

Pourquoi les bons messages de commit sont-ils importants ?

Les bons messages de commit aident de plusieurs manières pratiques :

Comprendre les modifications : Ils fournissent un contexte immédiat sur ce qu'un commit spécifique introduit ou modifie, ce qui fait gagner du temps lors de la révision du code ou du rappel des décisions passées.
Débogage : Lors de la recherche de bogues, un historique de commit clair vous permet d'identifier précisément quand et pourquoi une modification problématique a été introduite.
Collaboration : Pour les membres de l'équipe rejoignant un projet ou revisitant du code ancien, des messages bien rédigés facilitent la compréhension de la trajectoire de développement du projet.
Révisions de code : Ils offrent aux réviseurs un aperçu de l'intention derrière les modifications, facilitant ainsi des retours plus productifs et ciblés.
Outils automatisés : De nombreux outils Git, tels que les générateurs de changelog et les créateurs de notes de version, dépendent des messages de commit pour fonctionner efficacement.
Registre historique : Ils servent de forme de documentation, préservant l'évolution de la base de code au fil du temps.

L'anatomie d'un excellent message de commit Git

Une structure universellement reconnue pour les messages de commit Git suit un modèle simple mais puissant : une ligne d'objet concise suivie d'un corps optionnel plus détaillé.

La ligne d'objet

La ligne d'objet est la première ligne de votre message de commit. Elle doit être un résumé impératif et bref des modifications. Considérez-la comme un titre pour le commit.

Directives clés pour la ligne d'objet :

Soyez concis : Environ 50 caractères est un objectif utile, pas une limite stricte. Gardez l'objet suffisamment court pour être scanné dans git log --oneline.
Utilisez le mode impératif : Commencez par un verbe qui décrit l'action, comme si vous donniez un ordre. Exemples : Fix, Add, Refactor, Update, Remove, Style.
Mettez une majuscule au premier mot : La convention standard consiste à mettre une majuscule à la première lettre de la ligne d'objet.
Ne terminez pas par un point : La ligne d'objet est un titre, pas une phrase.
Évitez d'utiliser git commit -m "message" pour les messages plus longs : Bien que pratique pour les notes courtes, cela peut conduire à des messages moins structurés. Utilisez git commit sans arguments pour ouvrir votre éditeur pour des messages plus complexes.

Exemples de bonnes lignes d'objet :

feat: ajouter le module d'authentification utilisateur
fix: résoudre la boucle infinie dans le traitement des données
docs: mettre à jour les étapes d'installation du README
refactor: simplifier le chargement des images
chore: mettre à jour les dépendances de développement

Le corps

Le corps du message de commit est l'endroit où vous fournissez plus de contexte et de détails. Il est séparé de la ligne d'objet par une ligne vide. Cette section est facultative mais fortement recommandée pour tout ce qui dépasse les modifications triviales.

Directives clés pour le corps :

Expliquez le 'pourquoi' et le 'comment' : Ne décrivez pas seulement ce qui a changé ; expliquez pourquoi la modification était nécessaire et comment elle a été implémentée. Quel problème ce commit résout-il ? Quel était le comportement précédent ? Quel est le nouveau comportement ?
Limitez les lignes à 72 caractères : C'est une convention de longue date qui améliore la lisibilité dans de nombreux outils Git et terminaux.
Utilisez des puces pour les listes : Si vous devez énumérer plusieurs modifications ou points, utilisez des puces pour plus de clarté.
Référencez les problèmes ou tickets : Si le commit est lié à un suivi de problèmes (par exemple, GitHub Issues, Jira), incluez le numéro de ticket pour la traçabilité.

Exemple d'un bon message de commit (Objet + Corps) :

feat: implémenter la page de profil utilisateur

Ce commit introduit la page de profil utilisateur, permettant aux utilisateurs de
consulter et de modifier leurs informations personnelles.

Auparavant, les utilisateurs ne pouvaient pas accéder à leurs détails de profil
ni les modifier. Ce changement ajoute une nouvelle route (`/profile`) et un
composant correspondant qui récupère les données utilisateur depuis l'API et
fournit des formulaires pour mettre à jour des champs comme le nom, l'email
et la biographie.

Lié au #123.

Types de messages de commit courants (Conventional Commits)

Suivre une convention pour les types de messages de commit peut encore améliorer la clarté et permettre l'outillage automatisé. La spécification Conventional Commits est une norme populaire qui promeut une approche structurée.

Les Conventional Commits utilisent un préfixe pour indiquer le type de modification :

feat (fonctionnalité) : Une nouvelle fonctionnalité est introduite dans la base de code.
fix (correction de bogue) : Un bogue est résolu.
docs (documentation) : Modifications de la documentation uniquement.
style (formatage) : Modifications qui n'affectent pas le sens du code (espaces blancs, formatage, points-virgules manquants, etc.).
refactor (refactorisation du code) : Un changement de code qui ne corrige ni un bogue ni n'ajoute une fonctionnalité.
perf (performance) : Un changement de code qui améliore les performances.
test (ajout de tests manquants ou correction de tests existants) : Ajout ou correction de tests.
build (modifications affectant le système de build ou les dépendances externes) : Exemples : scripts npm, webpack, etc.
ci (modifications des fichiers et scripts de configuration CI) : Exemples : Travis, Circle, BrowserStack, SauceLabs, etc.
chore (tâches de maintenance) : Tâches qui ne correspondent pas aux autres types, comme le ménage du dépôt.

Portée (Optionnelle) : Une portée peut être ajoutée au préfixe pour indiquer la partie de la base de code affectée. Par exemple : feat(auth): Ajouter l'authentification JWT.

Pied de page (Optionnel) : Utilisez le pied de page pour référencer des problèmes, marquer des changements cassants ou ajouter d'autres métadonnées. Conventional Commits utilise BREAKING CHANGE: pour les changements cassants.

Exemple utilisant Conventional Commits :

fix(api): corriger le point de terminaison pour la récupération des données utilisateur

Auparavant, le point de terminaison `/users/:id/data` renvoyait des informations
obsolètes. Ce commit met à jour le point de terminaison vers `/users/:id/profile`
qui récupère les données de profil utilisateur les plus récentes.

Ferme #456

Conseils pour rédiger d'excellents messages de commit

Commitez souvent, mais logiquement : Faites des commits petits et atomiques qui représentent un seul changement logique. Cela rend les messages plus faciles à écrire et à comprendre.
Rédigez les messages du point de vue du futur du projet : Imaginez que vous revenez sur ce commit dans six mois. De quelles informations auriez-vous besoin pour comprendre rapidement le changement ?
Soyez spécifique : Évitez les messages vagues comme "Mise à jour du code" ou "Corrections de bogues". Expliquez précisément ce qui a été mis à jour ou corrigé.
Utilisez des backticks pour les références de code : Si vous mentionnez des noms de fichiers, des fonctions ou des noms de variables, encadrez-les de backticks (`).
Relisez vos messages : Avant de commiter, prenez un moment pour lire votre message. A-t-il du sens ? Est-il clair ?

À retenir

Rédigez chaque message de commit pour la personne qui le lira lors d'une révision, d'un rollback ou d'un incident. Utilisez un objet impératif court, ajoutez un corps lorsque la raison n'est pas évidente et gardez chaque commit concentré sur un seul changement logique.