Blog de Jacques
Les Commits Conventionnels (ou Commits Sémantiques)
Aujourd’hui, rare sont les développeurs qui remettent en cause l’utilisation d’un logiciel de gestion des versions tel que «git» et pour la plupart, c’en est même devenu ou outil indispensable qu’ils utilisent tous les jours.
La tâche principale d’un logiciel de gestion des versions est de gérer plusieurs versions des fichiers qui composent un projet informatique (ou autre). Pour cela, le développeur effectue régulièrement des commits qui permettent de figer l’état des fichiers à un instant donné. Plus tard, le développeur pourra revenir à un état précédent ou consulter les modifications qui ont été faites entre deux commits. A chaque commit le développeur doit associer un texte qui décrit les changements faits depuis le commit précédent et c’est là que la créativité des développeurs est souvent mise à mal.
L’illustration suivante, publiée sur xkcd illustre de manière amusante comment évoluent ces messages:
Ces messages sont cependant importants pour comprendre comment le code évolue et aussi pour les autres développeurs qui essayent de comprendre ce qui a changé dans un logiciel.
Déjà en 2008, Tim Pope, sur son blog tbaggery, écrivait un article qui expliquait comment rédiger de bons messages. Plus tard, le forum 365GIT publiait lui aussi un article sur le sujet. En 2012, le projet erlang/OTP donnait lui aussi des directives concernant la rédaction des messages et en 2014, Chris Beam adressait également ce problème sur son blog
Ces conseils sont encore en partie valables, mais parallèlement à ces publications, une nouvelle «bonne pratique», encore plus précise, commençait à être adoptée, il s’agit des Commits Conventionnels. Le premier document que j’ai trouvé qui mentionne cette convention est le AngularJS Git Commit Message Conventions publié en 2011 et repris en 2015 sur le dépôt git de Angular avec le titre Angular Commit Message Guidelines. Ce document reste d’ailleurs souvent cité comme modèle pour les commits conventionnels et à inciter des projets tels que Karma à adopter les mêmes conventions.
La technique des commits conventionnels est parfois aussi appelé commits sémantiques, ce qui nous fait penser à la gestion sémantique de version et nous verrons que ces concepts sont en effet lié. Le terme «semantic commit» à été utilise par Jeremy Mack dans un article publié sur Sparkbox.
Voici à quoi ressemble un message qui suit la convention des commits conventionnels
fix(bazel): pin `@microsoft/api-extractor` (#32187)
The API of `@microsoft/api-extractor` changed in a minor version which
is causes an error when using dts flattening downstream.
API wil be updated on master #32185
PR Close #32187
On reconnait la structure suivante:
<type>[optional scope]: <description>
[optional body]
[optional footer]
Voici les «types» les plus couramment utilisés:
| Type | Signification / utilisation |
|---|---|
| feat | Introduction d’une nouvelle feature (fonctionnalité) |
| fix | Correction d’une erreur (bug) |
| docs | Modification de la documentation uniquement |
| style | Changement qui n’affecte pas la signification du code (espace, formatage, points-virgules manquants, etc.) |
| refactor | Changement de code qui ne corrige pas d’erreur et n’ajoute pas de fonctionnalité |
| perf | Changement de code qui améliore les performances |
| test | Ajout de tests manquants ou correction des tests existants |
| revert | Annule un commit précédent. Le message commencer par «revert:» : suivi du message du commit à annuler |
| build | Changement qui affectent le système de compilation ou les dépendances externes |
| ci | Modification des fichiers de configuration d’intégration continue (CI) |
| chore | Changement des scripts de construction du logiciel uniquement (pas de changement du code de l’application) |
En lien avec les commits conventionnels, une autre approche moderne consiste à remplacer le type du changement par un emoji. Voici quelques références qui vous permettront d’en savoir plus et qui devraient vous permettre de savoir si cette approche vous convient:
Comme mentionné plus haut, il existe des parallèles entre les commits conventionnels et la gestion sémantique de version. Pour rappel, un numéro de version qui suit la règle de gestion sémantique de version se compose de 3 parties principales : un numéro de version majeur (major), un numéro de version mineur (minor) et un numéro de version de correctif (patch). Le numéro de version de correctif est incrémenté quand il y a des corrections d’anomalies qui n’entrainent pas de problème de compatibilité avec la version précédente. Le numéro de version mineur est incrémenté lorsqu’il y a des ajouts de fonctionnalités rétrocompatibles. Le numéro de version majeur est lui incrémenté quand il y a des changements non rétrocompatibles avec la version précédente.
Pour faire le lien avec les commits conventionnels, un message de type feat est utlilsé pour introduire une nouvelle fonctionnalité et implique donc l’incrément du numéro de version mineur. Les autres types (fix, docs, style, …) n’apportent pas nouvelle fonctionnalité et impliquent l’incrément du numéro de version de correctif. Pour incrémenter le numéro de version majeur, il faut un changement qui casse la compatibilité avec la version précédente. Il n’y a pas type précis pour indiquer ce genre de changement et la solution est de mettre le texte BREAKING CHANGE (tout en majuscules) dans la description ou dans le corps du message. Voici un exemple pour un tel message:
refactor(compiler): split compiler and core (#18683)
After this, neither @angular/compiler nor @angular/comnpiler-cli depend
on @angular/core.
This add a duplication of some interfaces and enums which is stored
in @angular/compiler/src/core.ts
BREAKING CHANGE:
- `@angular/platform-server` now additionally depends on
`@angular/platform-browser-dynamic` as a peer dependency.
PR Close #18683
On trouve aujourd’hui des outils qui permettent de comprendre les commits conventionnels et d’automatiser l’incrément de version et la production de «release» pour un logiciel. Le premier outil s’appelle «semantic-release» et est décrit dans ce document. L’autre projet est «go-semrel-gitlab» et à été conçu spécialement pour les programmes écrits en go.
J’espère que cet article vous permettra d’écrire de meilleurs messages. En tous cas, moi je vais utiliser le plus possible ces conventions et également les nouveaux outils de semantic release.