Conventional Commit

Mise à jour : 21/01/2025

Adopter une convention claire pour ses messages de commit n’est pas seulement une question de style, mais une vraie clé pour un workflow Git efficace. Les Conventional Commits sont là pour apporter de la structure, faciliter la compréhension des changements et automatiser des tâches comme le versioning ou les déploiements. À mon avis, c’est un standard incontournable pour les équipes qui veulent gagner en productivité et en lisibilité.

Origine des Conventional Commits

Les Conventional Commits ont émergé pour répondre à un besoin simple : standardiser les messages de commit pour qu’ils soient compréhensibles par les humains… et les outils. Ils s’inscrivent dans une lignée d’outils orientés DevOps, comme les semver (versions sémantiques), pour mieux gérer les changements dans les projets logiciels. À l’origine, cette convention a été popularisée par les développeurs cherchant à automatiser la génération des versions et des changelogs. Un vrai gain de temps, si vous voulez mon avis !

Les règles fondamentales

Les Conventional Commits reposent sur quelques règles simples mais puissantes. Voici les principales :

Structure d’un message de commit

Un message de commit conforme à la convention suit une structure standardisée. Voici ses éléments détaillés :

Le type : Il indique l’objectif du commit, comme :
- feat : pour une nouvelle fonctionnalité.
- fix : pour une correction de bug.
- docs : pour des changements de documentation.
- D’autres comme style, refactor, test, etc.
Le scope (optionnel) : Une précision sur la partie du projet affectée. Exemple : auth, api, ou UI.
La description : Une phrase concise expliquant le changement. Pas de point final.
Les détails (facultatifs) : Si besoin, une section supplémentaire peut être ajoutée après une ligne vide pour détailler ou fournir un contexte :
```
BREAKING CHANGE: les anciennes API ont été supprimées.
```

Exemple complet :

fix(auth): correction d'un bug d'expiration de session

Les sessions utilisateurs expiraient prématurément. La logique a été ajustée pour respecter le délai configuré.

Respecter cette structure rend les commits plus faciles à comprendre, même des mois plus tard.

Les principaux types de commits

Les Conventional Commits définissent plusieurs types standards qui indiquent la nature du changement. Voici les plus courants :

feat : Pour l’ajout d’une nouvelle fonctionnalité. Exemple :
```
feat(ui): ajout d'un mode sombre
```

fix : Pour une correction de bug. Exemple :

fix(api): correction du format de réponse JSON

docs : Pour les changements dans la documentation, comme les fichiers README. Exemple :
```
docs: mise à jour des instructions d'installation
```
style : Pour des changements de style de code (indentation, espaces, etc.) sans impact sur la logique. Exemple :
```
style(css): suppression des marges inutiles
```
refactor : Pour des modifications qui améliorent le code sans changer son comportement. Exemple :
```
refactor(api): simplification des conditions de validation
```
test : Pour l’ajout ou la mise à jour de tests. Exemple :
```
test(auth): ajout de tests unitaires pour la connexion
```
chore : Pour des tâches sans impact direct sur le code fonctionnel, comme la mise à jour des dépendances. Exemple :
```
chore(deps): mise à jour de lodash vers la version 4.17.21
```

À mon avis, utiliser ces types aide énormément à comprendre d’un coup d’œil la finalité d’un commit, surtout sur des projets complexes.

Gestion des scopes (facultatif mais recommandé)

Le scope dans un message de commit permet d’identifier précisément la partie du projet impactée. C’est optionnel, mais franchement, ça fait une vraie différence dans les projets d’envergure.

Pourquoi utiliser des scopes ?

Les scopes offrent une granularité supplémentaire. Ils permettent de répondre à la question : “Quelle partie du code est concernée par ce changement ?” Par exemple, dans une application, vous pourriez avoir des scopes comme auth, api, ui, ou encore backend.

Exemple d’utilisation des scopes :

Voici quelques exemples concrets pour illustrer leur utilité :

Ajout d’une nouvelle fonctionnalité liée à l’authentification :
```
feat(auth): ajout de la gestion OAuth
```

Correction d’un bug dans l’interface utilisateur :

fix(ui): correction de l'affichage des erreurs dans le formulaire

Réorganisation du code dans une API :

refactor(api): simplification des endpoints REST

Quand éviter les scopes ?

Si le changement concerne l’ensemble du projet ou qu’il est difficile à rattacher à une seule partie, vous pouvez simplement omettre le scope. Exemple :

chore: mise à jour des configurations de build

Personnellement, je recommande de toujours les utiliser quand c’est possible. Ça donne une vue d’ensemble beaucoup plus claire, surtout quand le projet prend de l’ampleur.

Les outils pour les Conventional Commits

Pour adopter efficacement les Conventional Commits, il existe plusieurs outils pratiques qui automatisent et vérifient leur utilisation. Voici les principaux :

Outils en ligne de commande

commitlint : Cet outil permet de valider vos messages de commit en fonction des règles des Conventional Commits. Si un message ne respecte pas le format attendu, il est rejeté.

Installation :

npm install --save-dev @commitlint/{config-conventional,cli}

Configuration : Créez un fichier commitlint.config.js :

module.exports = { extends: ['@commitlint/config-conventional'] };

Ajoutez un hook Git avec husky pour automatiser la vérification :

npm install --save-dev husky

npx husky init

# Add commit message linting to commit-msg hook
echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg
# Windows users should use ` to escape dollar signs
echo "npx --no commitlint --edit `$1" > .husky/commit-msg

Utilisation : À chaque commit, le message sera validé automatiquement.

git commit -m 'test'
⧗   input: test
✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]

✖   found 2 problems, 0 warnings
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

Commitizen : Une alternative qui simplifie la rédaction de messages conformes. Cet outil guide l’utilisateur avec une interface interactive.
- Installation :
  Terminal window
```
npm install -g commitizen
```
- Utilisation : Lancez la commande suivante et laissez-vous guider :
  Terminal window
```
git cz
```

Extensions VS Code pour les Conventional Commits

Voici une liste des extensions Vs Code qui facilitent l’adoption des Conventional Commits :

Conventional Commits : Ajoute une interface pour rédiger des messages de commit conformes. Vous sélectionnez le type, le scope, et ajoutez une description directement dans l’éditeur. Conventional Commits ↗
Commitizen Support** : Intègre Commitizen dans VS Code pour rédiger vos commits de manière interactive. Très pratique pour les débutants. Commitizen Support ↗
CommitLint : Valide vos messages de commit directement dans VS Code pour s’assurer qu’ils respectent la convention des Conventional Commits. CommitLint ↗

Avec ces outils, vous pouvez non seulement rédiger des commits conformes, mais aussi valider et visualiser leur impact sur votre workflow. Si je devais n’en choisir qu’une, l’extension Conventional Commits reste, à mon avis, la plus adaptée pour commencer.

À mon avis, ces outils sont indispensables pour garantir une adoption cohérente et automatiser tout le processus. Une fois en place, vous n’aurez plus à vous soucier des erreurs humaines !

Intégration avec les outils CI/CD

Les Conventional Commits ne se contentent pas d’améliorer la clarté des messages de commit : ils deviennent aussi des alliés puissants pour automatiser vos workflows avec des outils CI/CD comme Gitlab CI.

Génération automatique de changelogs : Les commits structurés permettent de produire des journaux de modifications avec des outils comme standard-version. Exemple : les commits feat et fix se traduisent directement en nouvelles versions ou en correctifs dans le changelog.
Versioning sémantique : Couplés à semver (version sémantique), les Conventional Commits définissent automatiquement si une mise à jour est majeure, mineure ou un simple correctif. Exemple :
```
feat: ajout de la gestion des webhooks
BREAKING CHANGE: suppression des anciennes API
```
Ici, un changement majeur sera déclenché.
Déploiements automatiques :

Avec des outils comme Gitlab CI, les messages de commit peuvent être utilisés pour déclencher différents pipelines, comme une mise en production après un commit feat ou fix.

Vous pouvez configurer un pipeline CI/CD qui réagit aux types de commits. Par exemple :

stages:
  - test
  - deploy

deploy:
  stage: deploy
  script:
    - echo "Déploiement en cours pour un commit de type feat ou fix"
  only:
    - /^feat|^fix/

Adopter cette intégration, à mon avis, transforme complètement la gestion de projet. Les Conventional Commits deviennent une brique essentielle pour une chaîne CI/CD fluide et robuste.

Les bonnes pratiques

Adopter les Conventional Commits, c’est bien. Mais pour vraiment en tirer parti, il est essentiel de suivre quelques bonnes pratiques. Voici mes recommandations personnelles :

Convenir des types en équipe : Même si la convention propose des types standards comme feat, fix, ou docs, chaque équipe peut adapter ces types selon ses besoins. Par exemple, vous pourriez ajouter des types comme perf pour des optimisations ou ci pour des changements dans les pipelines. Documentez ces choix pour que tout le monde soit aligné.
Utiliser des descriptions claires : La description du commit doit être concise mais explicite. Bannissez les messages vagues comme “fix bug”. Exemple :

fix(auth): correction du timeout d'expiration des sessions utilisateur

Ne pas surcharger un commit : Un commit doit se concentrer sur une seule tâche ou modification. Évitez les commits trop larges qui rendent l’historique difficile à lire. Si nécessaire, découpez les changements en plusieurs commits.
Valider automatiquement les commits : Implémentez un outil comme commitlint pour empêcher les commits non conformes. Ça garantit une adoption cohérente des Conventional Commits, même pour les nouveaux membres de l’équipe.
Utiliser un processus interactif : Des outils comme Commitizen ou des extensions VS Code permettent de rédiger vos messages de manière guidée. Idéal pour éviter les erreurs au début.
Inclure les scopes quand c’est pertinent : Même si le scope est optionnel, il permet d’avoir une vision plus précise de l’impact des changements. À mon avis, cela devient crucial pour les projets complexes.
Impliquer toute l’équipe : Les Conventional Commits ne fonctionnent que si tout le monde les utilise. Formez vos collègues, partagez des ressources, et encouragez leur adoption.
Automatiser la génération des changelogs : Avec des outils comme standard-version, utilisez vos messages de commit pour créer des changelogs automatiquement. Cela vous évite des heures de rédaction fastidieuse.
Revoir régulièrement l’utilisation Prenez le temps d’évaluer si les types utilisés et les pratiques mises en place répondent aux besoins de votre projet. Ajustez-les au fil du temps.

Conclusion

Les Conventional Commits ne sont pas qu’une simple convention : ils représentent une pratique essentielle pour structurer vos workflows Git. En adoptant ce format, vous gagnez en clarté, en productivité, et en collaboration au sein de votre équipe. Couplés à des outils de validation, d’automatisation des versions et des changelogs, ils deviennent une véritable brique de vos pipelines CI/CD.

À mon avis, commencer par ces conventions est un petit effort pour un grand résultat. Une fois que vous et votre équipe les maîtrisez, il est difficile d’imaginer revenir en arrière ! Si vous ne l’avez pas encore essayé, pourquoi ne pas vous lancer aujourd’hui ? Vous verrez, vos futurs vous remercieront !

Plus de ressources

Conventional Commits ↗