Mieux structurer ses messages de commits avec la spécification Conventional Commits

Fabien

Fabien, Architecte web 16 décembre 2021

La spécification Conventional Commits a pour objectif de mieux structurer les messages de commit. Leur donner une structure permet d’avoir davantage de lisibilité sur l’historique du projet. Cela permet aussi de pouvoir utiliser des outils de génération automatique de changelog, de numéro de version...

Principe de la spécification Conventional Commits

La spécification conventional commits propose d’organiser le message de son commit en différentes parties comme ceci :

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

Type

Le premier élément type est obligatoire et permet de classer le commit dans une catégorie. Les deux principaux types :

  • feat : une nouvelle fonctionnalité
  • fix : un correctif de bug

Autre élément important de cette partie, le symbole “!” qui annonce un Breaking Change.

Avec ces deux types par défaut et la gestion de BC, notre projet peut suivre la gestion SemVer de cette façon :

  • les commits de type fix concerneront les modifications de type correctif
  • les commits de type feature concerneront les modifications de type mineure
  • un breaking change créera une modification de type majeure

On peut aussi utiliser des types plus spécifiques qui détaillent davantage les modifications apportées :

  • build : des changements qui concernent le système de build ou d’une dépendance externe (exemple : gulp, npm)
  • ci : des changements de configuration ou de script lié au CI docs: pour des modifications dans la documentation
  • perf : une modification liée aux performances
  • refactor : une modification qui ne concerne ni un correctif de bug ou un ajout de fonctionnalité
  • style: changement qui n’affecte pas le fonctionnement du code (espace, indentation, point-virgule manquant, etc.)
  • test : ajout ou correction de test
  • chore : autre changement qui ne concerne pas le code source ou test
  • revert : annule un commit précédent

Le type doit toujours être suivi de “:” et d’un espace.

Scope

Le scope est un élément optionnel qui permet de préciser le contexte du changement. Il est libre et correspond souvent soit à un module, une fonctionnalité ou le nom d’un outil.

Il doit être renseigné entre parenthèses.

Subject

Cette partie obligatoire est la description succincte de la modification, la partie commentaire d’un commit classique en général.

Body

Le body est optionnel et correspond au message détaillé des changements. Il peut contenir plusieurs lignes et paragraphes.

Footer

Le footer est aussi optionnel, mais permet de compléter le commit en cas de modification majeur avec la clé BREAKING CHANGE : suivi d’une description.

Il peut aussi contenir d’autre clé au format git trailer comme des informations permettant de lier un commit au ticket par rapport à son système d’intégration continue:

  • refs #123
  • Closes #123

Exemple de commits générés avec ce format

➤ Exemple avec le minimum d’information (type + subject)

feat: allow provided config object to extend other configs

➤ Exemple avec en plus un breaking change :

refactor!: drop support for Node 5

➤ Exemple avec un scope de renseigner :

docs(animations): update developers on state of package (#44014)

➤ Exemple avec body et footer renseigner :

fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are obsolete now.

Reviewed-by:
Z Refs: #123

Outils pour faciliter la création de commit au format Conventional Commits

  • De nombreux outils existent pour mettre en place cette convention dans votre projet. En voici une sélection :
  • commitizen : un package npm pour créer des commits de manière interactive via la ligne de commande
  • hook git : un hook git pour controler que le message ait le bon format
  • Conventional Commit, Git Commit Template, qui sont des plugins pour les IDE de JetBrains
  • Conventional Commits, qui est une extension pour VSCode

Retour d’expérience sur le format Conventional Commits

L’utilisation de la spécification conventional commits peut paraître dans un premier temps ennuyeuse. Néanmoins, on peut se rendre compte au fil de son utilisation que les modifications sont mieux découpées et organisées. C'est un avantage de taille pour le développement et la maintenance des projets.

De plus, comme nous pourrons le démontrer prochainement, la mise en place de cette convention est une première étape dans l’automatisation de nombreux process de gestion de projet.