Xavier Kress :: Architecte logiciel / Développeur Full Stack (Java - Spring / Angular) / Formateur Spring - Agile

conventional commits

Adoptez les Conventional Commits pour structurer et automatiser vos projets

Combien de fois avez-vous ouvert l’historique Git d’un projet pour tomber sur des commits du genre :

Markdown
"fix"
"changement"
"correction bug"
"test"
"wip"

Et vous vous êtes demandé :

  • Qu’est-ce que ça corrige exactement ?
  • Est-ce que c’est lié à une nouvelle fonctionnalité ou à une refactorisation ?
  • Puis-je m’appuyer sur cet historique pour générer un changelog fiable ?

Ce flou est fréquent dans les projets. Et c’est précisément ce que les Conventional Commits viennent résoudre : définir une convention claire pour nommer vos commits, en imposant une structure simple et normalisée.

Qu’est-ce que le format Conventional Commits ?

Les Conventional Commits sont une convention d’écriture de messages de commit Git, destinée à rendre l’historique plus clair, lisible et exploitable par des outils.

Le format standard est :

Markdown
type(scope): description

[optional body]

[optional footer]

Les types de commits

Le champ <type> est obligatoire et indique l’intention du changement. Les plus courants sont :

  • feat : ajout d’une nouvelle fonctionnalité
  • fix : correction d’un bug
  • docs : modifications de documentation
  • style : changements qui n’affectent pas le sens du code (formatage, indentation…)
  • refactor : modifications de code qui n’ajoutent pas de fonctionnalité et ne corrigent pas de bug
  • perf : amélioration des performances
  • test : ajout ou modification de tests
  • build : changements liés au système de build ou aux dépendances
  • ci : changements pour la configuration de l’intégration continue
  • chore : tâches diverses qui ne modifient pas le code applicatif

Exemple d’un message de commit :

Markdown
feat(auth): ajout de la fonctionnalité de réinitialisation de mot de passe

Cette fonctionnalité permet aux utilisateurs de réinitialiser leur mot de passe via un lien envoyé par e-mail.

BREAKING CHANGE: Les anciennes URLs de réinitialisation ne sont plus valides.

Le scope

Le scope est optionnel mais recommandé. Il précise la zone du code impactée : un module, un composant, un domaine fonctionnel.
Cela facilite la lecture et permet des changements ciblés dans un changelog.

Le footer

C’est ici qu’on indique des informations de versionning ou de suivi, par exemple :

  • BREAKING CHANGE : pour indiquer une incompatibilité avec les versions précédentes
  • Liens vers des tickets
  • Références d’issues fermées

Pourquoi les adopter ?

Amélioration de la lisibilité et de la collaboration

Les Conventional Commits imposent une discipline dans la rédaction des messages. Cela rend chaque commit plus lisible et compréhensible pour l’ensemble de l’équipe, en particulier lors de la revue de code ou de la recherche de bugs.

Automatisation des tâches

L’un des principaux avantages est la possibilité d’automatiser certaines tâches grâce aux messages standardisés :

  • Génération automatique de changelogs : Des plugins Maven comme git-changelog-maven-plugin ou maven-conventional-changelog analysent directement l’historique Git au format Conventional Commits pour générer des changelogs détaillés au format Markdown, HTML ou texte.
  • Gestion sémantique des versions : En combinant les Conventional Commits avec un plugin Maven comme git-changelog-maven-plugin (goal semantic-version), vous pouvez automatiser le calcul de la prochaine version (major, minor ou patch) en fonction des types de commits détectés (feat, fix, BREAKING CHANGE, etc.).
    • Un bump de patch (pour un fix)
    • Un bump de minor (pour un feat)
    • Un bump de major (pour un BREAKING CHANGE)

Comment mettre en place les Conventional Commits ?

1. Définir une convention au sein de l’équipe

Avant tout, il est important de former l’équipe à utiliser cette norme et de s’assurer que tout le monde comprend les types et leur utilisation.

2. Utiliser des outils pour valider les commits

Git permet d’exécuter un script avant d’accepter un commit.
Dans un projet Java, on peut utiliser un simple script Bash placé dans .git/hooks/commit-msg

Bash
#!/bin/bash
commit_message=$(cat "$1")
pattern="^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([^)]+\))?(!)?: .{1,72}"
if ! [[ $commit_message =~ $pattern ]]; then
  echo "Message de commit non valide."
  echo "Format attendu : type(scope): description"
  echo "Types : build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test"
  exit 1
fi

Pour s’assurer que les commits sont conformes avant un déploiement, on peut exécuter ce même script dans le pipeline (ex. Jenkins, GitLab CI).
Cela se fait simplement en important le script dans l’étape de build et en l’appliquant sur la plage de commits à vérifier.

3. Générer automatiquement un changelog

Le plugin Maven git-changelog-maven-plugin permet de générer un changelog à partir de l’historique Git, en tirant parti du format Conventional Commits.

Bash
mvn se.bjurr.gitchangelog:git-changelog-maven-plugin:git-changelog

Exemple de sortie :

Markdown
### Features
* **api:** ajout de la pagination sur /users
* **ui:** ajout du tri par date

### Bug Fixes
* **auth:** corrige la validation des tokens expirés

4. Automatiser le versioning sémantique

Le même plugin propose la goal semantic-version qui calcule la prochaine version en suivant les règles du Semantic Versioning :

  • fix → incrémente le patch
  • feat → incrémente la minor
  • BREAKING CHANGE → incrémente la major

Commande :

Bash
mvn se.bjurr.gitchangelog:git-changelog-maven-plugin:semantic-version

Le plugin analyse l’historique Git et renvoie la version calculée.
Cette valeur peut ensuite être injectée dans le pom.xml ou utilisée pour automatiser une release avec maven-release-plugin.

Bonnes pratiques

  • Relire chaque message de commit avant de valider.
  • Ne pas mélanger plusieurs changements sans lien dans un même commit.
  • Utiliser le scope pour cibler précisément la zone modifiée.
  • Documenter la convention dans un fichier CONTRIBUTING.md pour les nouveaux arrivants.
  • Automatiser au maximum la génération du changelog et le versioning pour éviter les oublis.

Conclusion

Mettre en place les Conventional Commits dans un projet, ce n’est pas qu’une question de style :

  • Vous obtenez un historique clair et exploitable
  • Vous facilitez l’automatisation (changelog, versioning)
  • Vous améliorez la maintenabilité sur le long terme

Avec un simple hook Git pour la validation et le plugin git-changelog-maven-plugin pour la génération et le calcul de version, vous disposez d’un workflow lisible, structuré et prêt pour l’automatisation complète des releases.