Conventional Commits

Présentation

Un projet collaboratif ne s'improvise pas. Il repose sur des méthodes structurées et des conventions claires qui simplifient l'organisation et la communication au sein de l'équipe. En suivant des pratiques standardisées, chacun peut contribuer efficacement, accéder rapidement aux informations utiles et intégrer son travail sans friction.

Les conventional commits établissent des règles claires pour uniformiser la structure des messages de commit. Cette convention permet de rendre l'historique des modifications explicite et facile à interpréter, ce qui facilite le suivi des évolutions du projet.

Format du message

La convention Conventional Commits propose un format précis pour rédiger les messages de commit, afin d'unifier et de clarifier l'historique d'un projet :


                    <type>(<scope>): <description>

                    [corps optionnel]

                    [pied de commit optionnel]

type : Reflète l'intention du commit.
scope (optionnel) : Précise la partie du code impactée.
description : Un résumé concis des changements.
corps (optionnel) : Fournit des détails supplémentaires (implémentations, raisons, etc.).
pied de commit (optionnel) : Souvent utilisé pour référencer un ticket ou une issue, ou pour ajouter des breaking changes (changements majeurs dans le code qui obligent à modifier l'utilisation existante).

En-tête du commit

L'en-tête du commit, qui correspond à la première ligne du message, doit être concis et ne pas dépasser 50 caractères. Cela inclut le type, le scope (optionnel) et la description succincte.

Type

Le type est un élément obligatoire qui décrit l'intention principale du commit, comme l'ajout d'une fonctionnalité, la correction d'un bug ou la mise à jour de la documentation.

feat : introduit une nouvelle fonctionnalité dans le code.
fix : apporte une correction de bug.
docs : concerne des modifications de la documentation.
style : implique des changements qui n'affectent pas la logique du code, comme le formatage ou les espaces.
refactor : représente une refonte du code sans ajout de fonctionnalité ni correction de bug.
test : ajoute ou modifie des tests existants.
chore : concerne des tâches de maintenance comme la mise à jour des dépendances.

Scope

Le scope est un élément optionnel qui permet de préciser la partie du code concernée par le commit.

auth : se rapporte au module d'authentification.
ui : se rapporte à l'interface utilisateur.
deps : se rapporte aux dépendances.
api : se rapporte aux modifications de l'interface de programmation.

Description

La description de l'en-tête du commit résume brièvement et précisément la modification apportée. Elle suit le type et le scope éventuel, et commence par un verbe d'action à la forme impérative, comme "add", "fix", ou "update". La description commence toujours par une lettre minuscule et ne contient pas de point final. L'objectif est de fournir une information claire et rapide sur le changement, lisible dans les outils d'historique de commits comme git log --oneline.

Exemples d'en-têtes

Ajoute la fonctionnalité de connexion avec Google.


                            feat(auth): add Google login support

Résous un problème d'affichage sur les petits écrans.


                            fix(ui): resolve display issue on small screens

Actualise la bibliothèque axios vers la dernière version.


                            chore(deps): update axios to v1.2.3

Ajoute une nouvelle route pour les utilisateurs.


                            feat(api): add new route for user endpoints

Corps du Commit

Le corps du commit est une section optionnelle qui permet d'ajouter des détails supplémentaires aux modifications décrites dans l'en-tête. Bien qu'il soit facultatif, il est particulièrement utile pour fournir des explications techniques, des contextes ou des justifications pour les changements effectués.

Le corps doit respecter certaines règles pour rester lisible et cohérent :

Fournissez des informations pertinentes, comme les raisons du changement, les détails d'implémentation ou des cas particuliers.
Séparez l'en-tête et le corps par une ligne vide pour garantir une distinction claire entre ces deux sections.
Limitez chaque ligne à une longueur maximale de 72 caractères pour éviter le troncage dans les interfaces Git.
Divisez le contenu du corps en paragraphes distincts pour une meilleure lisibilité, en insérant une ligne vide entre chaque paragraphe.

Exemples de corps

Dans l'exemple suivant, l'en-tête indique clairement qu'il s'agit d'une nouvelle fonctionnalité liée à la recherche. Le corps, rédigé en un seul paragraphe, décrit brièvement l'ajout de la fonctionnalité, les technologies utilisées, et l'impact attendu sur l'expérience utilisateur.


                    # En-tête :
                    feat(search): add search bar with autocomplete

                    # Corps :
                    This commit implements a search bar with autocomplete functionality. 
                    The feature uses a JavaScript library to suggest results dynamically 
                    as the user types. This enhancement aims to improve user experience 
                    by making it faster and easier to find content.

Dans l'exemple suivant, l'en-tête précise l'ajout d'une nouvelle fonctionnalité de connexion via Google OAuth. Le corps du commit est structuré en deux paragraphes. Le premier détaille les modifications techniques apportées, tandis que le second met l'accent sur les bénéfices pour l'utilisateur final.


                    # En-tête :
                    feat(auth): add support for Google OAuth login

                    # Corps (paragraphe 1) :
                    This commit introduces support for Google OAuth2.0 login. 
                    It integrates the Google OAuth API and updates the backend 
                    to handle token validation. 

                    # Corps (paragraphe 2) :
                    This change enhances user convenience and ensures secure 
                    authentication via third-party accounts.

Pied de Commit

Le pied de commit est une section optionnelle située à la fin du message. Il est utilisé pour inclure des informations supplémentaires qui ne sont pas directement liées à la description ou au corps, mais qui sont importantes pour le suivi du projet. Il peut contenir des références à des tickets ou issues, ou des indications spécifiques comme des changements majeurs (breaking changes).

Le pied doit respecter les conventions suivantes :

Séparez-le du corps du commit par une ligne vide.
Rédigez chaque ligne de manière concise et explicite.
Utilisez les mots-clés standardisés comme BREAKING CHANGE, Closes, ou Refs pour clarifier son objectif.

Voici les usages principaux du pied de commit :

BREAKING CHANGE : Utilisé pour signaler un changement majeur ou une rupture de compatibilité dans le projet. Ce mot-clé est suivi d'une explication claire des modifications et des impacts. Dans ce contexte, un point d'exclamation ! peut être ajouté immédiatement après le type ou le couple type/scope pour indiquer qu'un changement majeur a été introduit.
Closes ou Fixes : Utilisé pour référencer un ticket ou une issue, indiquant qu'il est résolu par ce commit. Cela signifie que le problème ou la tâche décrite dans l'issue est complètement terminée. Dans des outils comme GitHub, cela ferme automatiquement l'issue lorsqu'on fusionne le commit.
Refs : Utilisé pour faire référence à un ticket ou une issue sans indiquer qu'il est entièrement résolu. Cela permet de signaler que le commit est lié à une tâche ou un problème en cours, mais qu'il reste encore du travail à faire pour le terminer.

Exemples de pieds de commit

Dans l'exemple suivant, l'en-tête indique une nouvelle fonctionnalité majeure liée à la migration vers OAuth2 pour l'API. Le point d'exclamation ! placé après le type et le scope signale qu'il s'agit d'un changement majeur, c'est-à-dire une modification qui casse la compatibilité avec les versions précédentes du projet. Le corps décrit brièvement les changements techniques et leur objectif, tandis que le pied de commit, marqué par BREAKING CHANGE, fournit des détails sur l'impact de cette rupture et les ajustements nécessaires pour les développeurs.


                    # En-tête :
                    feat(api)!: switch to OAuth2 authentication

                    # Corps :
                    This commit updates the authentication system to use OAuth2 
                    instead of basic authentication. This change enhances security 
                    and aligns with industry standards.

                    # Pied de commit :
                    BREAKING CHANGE: The login API now requires OAuth2 tokens 
                    instead of username and password for authentication.

Dans cet exemple, l'en-tête indique la résolution d'un bug lié à l'affichage sur les petits écrans. Le corps décrit clairement la nature du problème et les ajustements techniques réalisés pour le corriger. Le pied de commit utilise Closes pour référencer et marquer comme résolue une issue spécifique #42.


                    # En-tête :
                    fix(ui): resolve layout issue on small screens

                    # Corps :
                    This commit adjusts the CSS grid layout to fix the display
                    problem occurring on screens smaller than 768px.

                    # Pied de commit :
                    Closes #42

Dans cet exemple, l'en-tête mentionne une refonte du module d'authentification, sans introduire de changement majeur. Le corps détaille l'optimisation technique effectuée pour améliorer la validation des jetons utilisateur. Le pied de commit utilise Refs pour indiquer que cette modification est liée à l'issue #123, mais qu'elle ne résout pas encore entièrement le problème.


                    # En-tête :
                    refactor(auth): improve token validation logic

                    # Corps :
                    This refactor optimizes the validation process for user tokens
                    but does not fully implement the new authentication system.

                    # Pied de commit :
                    Refs #123