Les messages de validation sont de courtes descriptions de chaque validation dans un système de contrôle de version comme Git. Lorsque vous apportez des modifications aux fichiers de votre projet, vous devez fournir un message expliquant ce qu’elles font ou pourquoi vous les avez apportées.



Les messages de validation constituent une forme de documentation et de communication. Ils jouent un rôle crucial dans le maintien d’un historique clair et organisé des versions d’un projet. Apprenez à rédiger de bons messages de validation et les autres membres de votre équipe apprécieront encore plus votre travail.


Structure d’un bon message de validation

Un bon exemple de message de validation comprend quatre sections : Type, Description, Corps et Pied de page.

Par exemple :

 <type>: <description>

[optional body]

[optional footer]

Type

Le type décrit le type de changement effectué dans le présent commit. Vous pouvez utiliser le système qui vous convient le mieux. Par exemple, voici quelques exemples de mots-clés que vous pouvez utiliser pour signaler chaque type de changement, ainsi que des exemples d’utilisation :

  • exploit: vos modifications introduisent une nouvelle fonctionnalité.
  • correctif: vous corrigez un bug.
  • refactoriser: votre modification refactore le code sans corriger de bogue ni ajouter de nouvelle fonctionnalité.
  • testVous pouvez utiliser l’option « test » lorsque vous effectuez des modifications liées aux tests. Par exemple, lorsque vous écrivez des tests avec Jest ou tout autre framework de test de votre choix.
  • corvée: changements non liés à un correctif, une fonctionnalité ou un test. Par exemple, la mise à jour des dépendances.
  • docs: lorsque vous mettez à jour la documentation.
  • style: modifications qui n’affectent pas la signification du code, telles que l’ajout d’espaces blancs, l’absence de points-virgules, etc.
  • perf: changements liés à l’amélioration des performances.
  • construction: lorsque vous effectuez des modifications qui affectent les fichiers de compilation.
  • ci: changements liés à l’intégration continue.
  • revert: lors du retour à un commit précédent.

Description

La « description » d’un message de livraison est un résumé concis et descriptif des modifications apportées à la livraison. Il s’agit d’un titre qui capture l’essence de la livraison.

Lors de la rédaction de la description, il convient de garder à l’esprit les éléments suivants :

  • Elle doit être suffisamment claire et précise pour décrire la livraison d’un seul coup d’œil.
  • Soyez bref et concis. L’idéal est de le limiter à 50 caractères ou moins.
  • Rédigez votre texte au présent, même si vous décrivez des changements déjà effectués.
  • Utilisez l’impératif lors de la rédaction.
  • Commencez-la par une majuscule.
  • Ne le terminez pas par un point.

Par exemple :

 feat: Implement dark mode toggle for home page

Cet exemple montre comment vous pouvez écrire la description d’une livraison qui implémente le mode sombre. Il utilise l’élément feat parce qu’il introduit une nouvelle fonctionnalité.

Corps (optionnel)

Le corps d’un message de livraison fournit des détails et un contexte supplémentaires sur les modifications apportées dans la livraison. Vous n’aurez pas toujours besoin d’un corps, mais il peut vous aider à fournir plus d’informations, à expliquer le raisonnement d’un changement ou à décrire des considérations techniques.

Voici quelques éléments à prendre en compte lors de la rédaction du corps d’un message de livraison :

  • Git n’enroule jamais le texte automatiquement, il faut donc l’enrouler manuellement à 72 caractères lorsque vous écrivez le corps du message. Cela donne à Git suffisamment de place pour indenter le texte, ce qui le rend plus lisible.
  • Utilisez le corps pour expliquer ce qui s’est passé dans la modification, pourquoi vous avez fait la modification, et le raisonnement derrière votre modification.
  • Vous devez laisser une ligne vide entre la ligne de description et le corps. Cela permet à Git de les distinguer.
  • Si la livraison introduit plusieurs changements ou affecte différentes zones de la base de code, envisagez d’utiliser des puces ou des paragraphes pour décomposer les modifications. Cela améliore la lisibilité et aide les lecteurs à comprendre les différents aspects de la livraison.

Par exemple :

 feat: Add GitHub as an OAuth provider

Integrate GitHub as an OAuth provider to enable seamless 
authentication with GitHub accounts.

- Implement OAuth authentication flow with GitHub API
- Configure necessary endpoints and settings for GitHub authentication
- Update user interface to include GitHub login option

L’exemple ci-dessus montre un bon message de validation Git pour une fonctionnalité qui ajoute GitHub comme fournisseur OAuth à votre application. Ce message de validation comporte une ligne de résumé concise (50 caractères ou moins), un texte explicatif plus détaillé (d’environ 72 caractères) et des puces pour des informations supplémentaires.

Le pied de page d’un message de livraison est une partie facultative qui fournit des informations supplémentaires ou des métadonnées relatives à la livraison. Elle est généralement placée après le corps du message, séparée par une ligne blanche. Le pied de page peut inclure différents types d’informations, comme des références à des problèmes connexes, des balises ou des notes spéciales.

Lorsque vous faites référence à des problèmes, des demandes d’extraction ou d’autres éléments connexes, utilisez la syntaxe appropriée ou le format requis par le système de suivi des problèmes de votre projet. Cela permet de s’assurer que les références sont correctement reconnues et liées.

Par exemple :

 feat: Add GitHub as OAuth provider

Integrate GitHub as an OAuth provider to enable seamless 
authentication with GitHub accounts.

- Implement OAuth authentication flow with GitHub API
- Configure necessary endpoints and settings for GitHub authentication
- Update user interface to include GitHub login option

Resolves: #123
See also: #456, #789

Le pied de page fait référence à la question connexe #123 et mentionne d’autres questions connexes #456 et #789 pour un contexte supplémentaire.


Ajout du message de validation

Vous pouvez écrire des messages de validation à l’aide de la commande -m suivi du message de livraison entre guillemets (facultatif mais recommandé).

L’option -m est idéal pour les messages de livraison courts, incluant généralement le type et la description.

Par exemple :

 git commit -m "chore: Change linter to ESlint"

Cependant, lorsque votre message de validation nécessite plus de détails, tels qu’un corps et un pied de page, il est préférable d’écrire la validation dans un éditeur de texte ou un IDE.

Alternativement, vous pouvez écrire de longs messages de livraison dans un fichier texte et utiliser la commande –file pour spécifier les messages de validation comme le contenu d’un fichier texte.

Par exemple :

 git commit --file commit_message.txt

Lorsque vous exécutez la commande ci-dessus, git utilisera le contenu du fichier comme message de livraison.

Vous pouvez également demander à git d’ouvrir votre éditeur par défaut pour écrire un message plus long. Si la variable d’environnement GIT_EDITOR ou EDITOR est définie, git ouvrira ce programme lorsque vous lancerez la commande bare git commit commande.


Pourquoi vous devez écrire de bons messages d’engagement

La rédaction de bons messages de validation est cruciale pour une collaboration efficace et la maintenance du code. Des messages clairs et descriptifs facilitent la compréhension, le débogage et les revues de code. Ils peuvent même contribuer à la documentation du projet ou aux notes de version.

Ils permettent le partage des connaissances, l’intégration en douceur et le contrôle des versions. La priorité accordée à la qualité des messages de validation améliore les processus de développement et garantit la maintenabilité de la base de code.