Comment bien écrire vos messages de commit ?

Découvrez les bonnes pratiques et une convention de nommage pour vos messages de commit avec Git !

Article publié le 15/04/2024, dernière mise à jour le 15/04/2024

La force de Git est bien évidemment de stocker et versionner toutes les modifications d’un code source au fil du temps, afin de garder un historique et de pouvoir revenir à une version antérieure s’il y a besoin.

Mais on ne peut parcourir un historique de manière efficace, que si l’on sait ce que l’on parcoure

En effet, les messages des commits (versions) sont une facette très importante de la gestion d’un projet de développement !

Chaque commit peut contenir un grand nombre d'infos importantes, et il est nécessaire de trouver une structure de message qui :

  • soit facilement compréhensible
  • pas trop difficile à écrire
  • qui hiérarchise bien les informations

Heureusement, il existe une convention qui coche toutes les bonnes cases : les conventional commits

nicolasbrondinbernard_An_opened_enveloppe_with_writing_on_it._1_46f2a0ac-3a21-4b3e-9ba8-212903a837b0.png

Conventional commits

Dans l’idéal, un message de commit doit contenir toutes les informations nécessaires à la bonne compréhension d’un humain, et donc :

  • Le type de changement (nouvelle fonctionnalité par exemple)
  • La portée du changement (la partie du code modifiée, comme un module)
  • La description de ce changement
  • Le numéro du ticket, ou “issue” corrigé (optionnel)

Et voici le format conseillé par cette convention :

<type>[optional scope]: <description>

[optional body]

[optional footer]

Ce qui donne un exemple de commit comme celui-ci :

fix(user): authenticate user with email instead of username

Issue #132

La spécification contient 15 règles précises à suivre, comme les types de commit : feat, fix, refactor, build, chore, ci, docs, style, test,…

Vous pourrez retrouver toutes les informations, et les valeurs possibles, liées à cette convention sur le site dédié : https://www.conventionalcommits.org/en/

En bonus : cette convention permet de parser les messages de commit assez facilement pour une machine, et donc de générer des changelogs par exemple !

Une variation personnalisée

À titre personnel, j’ai longtemps utilisé une variante (avant de connaitre la convention du dessus) assez proche, légèrement plus concise, comme ceci :

[TYPE] scope (#issue) - message

Ce qui donne des messages de commit ressemblant à ceci :

  • [REFACTOR] User (#5) - Merging User and Account models
  • [FIX] Notifications (#18) - Emails were not sending due to wrong smtp credentials
  • [FEATURE] Post (#65) - Images can be added to posts using the editor

Il est quand même très conseillé d’utilisé les conventional commits mais libre à vous d’opter pour celle-ci

Car une même une convention non-standard vaut mieux que pas de convention du tout (et ne parlons pas des commits sans message…)


Vous avez terminé l'article ?

Commentaires (0)

pour laisser un commentaire

Aucun commentaire pour l'instant