En tant que développeur, on peut se retrouver souvent à avoir du mal avec les commentaires de commit sur Git. On ne sait jamais trop quoi écrire dedans, et ça finit par être un peu confus. De plus, les commentaires de commit de nos collègues sont souvent très différents les uns des autres, ce qui rend la cohérence difficile à atteindre. Dans l'ensemble, on a l'impression que les commentaires de commit laissés sur nos projets ne sont pas très utiles. On aimerait bien des conseils pour nous aider à résoudre ce problème et à rendre nos commentaires de commit plus utiles et cohérents.
Parlons Conventional commits
La gestion de versions est l'une des pierres angulaires du développement logiciel moderne. Elle permet aux équipes de travailler de manière collaborative, de suivre l'évolution du code et de gérer les modifications de manière transparente.
Les Conventional Commits est une spécification visant à améliorer les messages de commit en général, elles offrent au lecteur un contexte précieux sur les changements apportés. Cette approche permet de savoir si un commit met en œuvre une nouvelle fonctionnalité, refactore du code existant, corrige un défaut, ajoute un test unitaire ou supprime du code, facilitant ainsi la compréhension des modifications apportées au code.
Examinons de plus près la pratique des Conventional Commits, comprenons pourquoi elle revêt une importance particulière et découvrons comment l'adopter.
Zoom sur la spécification
Les Conventional Commits ont le format suivant :
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Type :
Le champ <type> apporte du contexte au commit en indiquant le type de changement réalisé. Il peut prendre diverses valeurs comme "feat" (pour une nouvelle fonctionnalité), "fix" (pour résoudre un bug), "docs" (pour les ajustements dans la documentation) ou encore "chore" (pour des tâches de maintenance), et bien d'autres encore.
Les projets ont la liberté de définir leurs propres valeurs pour ce champ. En suivant des conventions spécifiques, comme celle d'Angular par exemple, on peut utiliser une variété de types de commit :
- Build: Quand un commit modifie la manière dont l'application est construite ou ajoute de nouvelles dépendances techniques.
- Ci: Quand un commit apporte des modifications à l'intégration continue.
- Style: Quand un commit change le style du code source.
- Refactor: Quand un commit refactore du code.
- Perf: Quand un commit améliore les performances de l'application.
- Test: Quand un commit améliore ou ajoute des tests.
Scope (optionnel) :
Souvent écrit entre parenthèses après le champ <type>, le champ <scope> est facultatif et permet de cibler un package ou un module spécifique de l'application concerné par le commit. Comme le champ <type>, il repose sur une liste de valeurs qui peut être définie par l'équipe de développement. En pratique, ce champ émerge naturellement à mesure que le projet se développe.
A noter qu’en ajoutant le caractère “!” après <type> ou <scope> on peut informer que le commit apporte des changements cassants.
Description :
Le champ <description> suit les champs <type> et <scope> après le caractère “:”. Il résume brièvement l’intention du contenu du commit.
Les champs <type>, <scope> et <description> forment la première ligne d’un message de commit. La taille de cette ligne est souvent limitée en taille de caractères.
Body (optionnel) :
En fonction des besoins, le champ <body> peut fournir des informations complémentaires sur la modification directement dans le message de commit.
Ce champ est capable d'accueillir plusieurs paragraphes destinés à étoffer les informations relatives à la modification effectuée dans le commit. En général, son usage vise à expliquer la motivation des changements plutôt qu'à détailler les modifications elles-mêmes, puisque ces dernières sont déjà disponibles dans la différence (diff) du commit.
Il convient cependant de noter qu'une limite de taille de 72 caractères est imposée par Git pour le champ <body>.
Footers (optionnel) :
Rédigés selon le format : <token>: <value>, ces champs sont optionnels et ont la capacité d'apporter des informations supplémentaires ou d'automatiser des actions en relation avec des systèmes tels que les outils de suivi de tickets, comme JIRA, s'ils sont configurés en conséquence.
Des exemples de footers :
- Closes : FEA-001, FEA-002 (fermera sur JIRA les tickets mentionnées)
- Resolves : BUG-001, BUG-002 (résoudra les bugs sous JIRA)
- Reviewed-by : John Doe (informe la ou les personne qui ont relue le commit)
Mais pourquoi l’utiliser ?
Les messages de commit au format Conventional Commits assurent une communication claire et cohérente concernant la nature des modifications apportées au code. Cette clarté facilite la compréhension rapide des évolutions du projet, aussi bien pour les membres de l'équipe que pour le public et les autres parties prenantes.
De plus, les commits structurés conformément aux Conventional Commits ont la capacité d'automatiser divers processus. Cela inclut la possibilité de déclencher automatiquement des actions telles que la génération de documentation, l'exécution de tests automatisés, voire le déploiement continu. Cette automatisation renforce l'efficacité du flux de travail de développement en réduisant les tâches manuelles répétitives.
Un autre avantage notable réside dans la possibilité de générer automatiquement des fichiers CHANGELOG (journal des modifications). Cette automatisation simplifie considérablement la gestion de l'historique des modifications du projet, en extrayant automatiquement les informations pertinentes des messages de commit structurés. Cela libère du temps et des ressources précieuses, permettant ainsi aux équipes de se concentrer davantage sur le développement du logiciel.
S’assurer de l’adoption de la convention dans un projet
L'adoption de conventions dans un projet peut sembler motivante et passionnante. Cependant, assurer leur pérennité dans un projet n'est pas une tâche facile.
Heureusement, il existe des outils qui peuvent garantir le respect des règles de notation des Conventional Commits. Ces outils peuvent être exécutés pendant les constructions (builds) sur les plateformes d'intégration continue ou être déclenchés grâce à des hooks GIT sur les machines des développeurs.
Dans l'écosystème, il existe des outils tels que Commitlint, écrit en Node.js, qui veillent à ce que les commits respectent les règles des Conventional Commits. Commitlint peut être configuré pour s'exécuter en tant que crochet (hook) pre-commit en utilisant Husky. De cette manière, lors de la création d'un commit, s'il ne respecte pas les règles définies, il sera automatiquement rejeté.
Mot de la fin
Les messages de commit Git et l'historique de votre dépôt sont des éléments importants qui doivent être traités de manière responsable. L'historique des commits peut être précieux s'il contient des informations significatives permettant à quelqu'un de comprendre l'état actuel d'une application en explorant son historique. Les conventional commits sont un outil puissant pour améliorer la gestion de versions et la collaboration au sein d'une équipe de développement. Ils permettent de clarifier les intentions derrière chaque modification et simplifient la recherche et la compréhension des changements apportés au code. En adoptant cette pratique, les équipes peuvent améliorer leur efficacité, réduire les erreurs et rendre leur code plus robuste. Alors, pourquoi ne pas commencer à utiliser les conventional commits dans votre prochain projet de développement logiciel ?
