Pourquoi les messages de vos commits sont essentiels : Adoptez les Conventional Commits pour un projet plus propre et maintenable

Introduction

On pense souvent qu’écrire un message de commit après avoir ouvert une pull request est une perte de temps et un moment où l’on ne prête que très peu d’attention. Pourtant, un message de commit est l’une des parties les plus importantes du code que l’on va pousser. Il est notamment nécessaire pour la traçabilité, la compréhension et la maintenabilité dans nos projets.

Souvent négligé et bâclé par de nombreux développeurs, on se retrouve vite avec un historique Git illisible et dans lequel il est difficile de naviguer. C’est dans ce contexte que les Conventional Commits entrent en jeu. Cette convention de nommage, dont la documentation est disponible ici, permet de standardiser les messages de commits à l’aide de quelques règles définies, facilite l’automatisation et améliore ainsi la communication au sein de nos projets techniques.

Qu’est-ce qu’un message de commit, et pourquoi est-il si important ?

Tout au long de nos projets, nous avons écrit des messages pour nos commits. Ils contiennent notamment :

• Un identifiant unique
• Nos fichiers modifiés
• Un auteur
• Un message

Nos messages de commit sont en réalité la seule partie narrative pour expliquer et documenter nos modifications, entre notre code et l’explication de nos modifications.

L’un des avantages de laisser un bon message de commit est de :

• Comprendre rapidement les modifications effectuées dans le code
• Faciliter notre débogage lors de l’exécution des commandes git blame ou git bisect

Les problèmes liés aux messages non standardisés

Lorsque les messages ressemblent à :

• final fix
• modification about the register system
• hot fix prod is KO

On ne comprend pas rapidement ce que les modifications touchent comme composantes essentielles de notre code, et encore moins quand on va devoir régler un bug en utilisant l’historique Git.

Les Conventional Commits : une norme simple et efficace

Conventional Commits est une norme qui s’impose maintenant depuis quelques années dans nos projets techniques. Elle propose une structure claire et lisible pour chacun de nos messages.

<type>(<scope>): <description>

Concernant les types, il en existe plusieurs, comme :

• feat : Lorsque le commit concerne l’ajout d’un nouveau comportement ou d’une nouvelle fonctionnalité
• fix : Lorsque le commit règle un comportement anormal d’une fonctionnalité déjà mergée
• chore : Lorsque le commit concerne une tâche non fonctionnelle mais plutôt une tâche de maintenance de l’application
• ci : Lorsque le commit concerne la modification des pipelines de CI
• refactor : Lorsque le commit concerne la non-modification d’un code fonctionnel mais que l’on a refactoré à l’intérieur de notre code

Pour les scopes, c’est un ajout d’information contextuelle supplémentaire. Il s’agit du domaine impacté par notre commit, plus large, que l’on donne comme repère clé. Suivant votre contexte métier ou applicatif, on pourrait avoir, à titre d’exemple :

• (utiq) : Si notre commit traite de la modification de la partie utiq de notre système
• (register-page) : Si notre commit traite plus largement de la page d’inscription de notre application

Libre à vous de décider ce que vous souhaitez mettre dans votre scope, c’est assez propre à chacun. Cependant, gardez à l’esprit que c’est le domaine impacté par le commit de manière large.

Pour les descriptions, c’est un texte résumé des modifications que vous apportez dans ce commit, de manière concise.

Quels sont les avantages concrets d’utiliser les Conventional Commits ?

• ✅ Une lisibilité accrue dans l’historique Git de votre projet
• ✅ Automatisation facile, notamment pour les changelogs
• ✅ Collaboration fluide : tous les membres de l’équipe parlent désormais le même langage
• ✅ Qualité logicielle : on encourage une meilleure discipline dans nos développements
• ✅ Productivité : on gagne du temps lors de la recherche de bugs grâce à notre historique Git
• ✅ Réduction de la frustration : on limite la frustration des équipes en leur faisant gagner du temps de compréhension

Comment mettre en place les Conventional Commits ?

1. Former votre équipe : Une simple note ou un article peut aider à faire accepter à votre équipe d’utiliser les Conventional Commits.
2. Configurer un linter Git : Après une période d’adaptation de quelques jours, mettez en place un linter Git pour faire appliquer la convention de manière automatique et éviter ainsi les oublis (ex: Husky, commitlint, Grumphp avec commit_message personnalisé).
3. Ajoutez une documentation claire : Dans votre projet ou dans votre système de documentation pour répertorier les différentes règles et options. Cela évitera les questions redondantes de vos équipes.
4. Prévoyez un atelier technique : Avec votre équipe, si vous voyez une difficulté particulière à la mise en place de cette convention, pour éviter tous les bloqueurs et frustrations qui pourraient apparaître. Profitez-en également pour sonder votre équipe à propos de ce système et avoir leurs retours d’expérience.
5. Optionnel : Si vous le souhaitez, vous pouvez automatiser en CI/CD pour générer automatiquement vos versions ou changelogs.

FAQ

Est-ce contraignant à long terme dans les projets ?

Absolument pas ! C’est une habitude que l’on prend vite et qui n’est pas coûteuse. Les équipes s’adaptent rapidement à cette nouvelle convention.

Conclusion

Que ce soit pour vos nouveaux projets ou vos projets actuels, désormais avec les Conventional Commits, dites adieu à vos historiques Git illisibles et place à la clarté.

Vos historiques Git deviennent désormais un levier de qualité, de collaboration et d’automatisation possible.

En adoptant les Conventional Commits aujourd’hui, vous transformez vos historiques Git en un véritable journal de bord fonctionnel, lisible, puissant et exploitable.