Comment écrire un message Git Commit efficace et utile

Les messages de validation sont de courtes descriptions de chaque validation dans un système de contrôle de version tel que 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

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 :

• feat: vos modifications introduisent une nouvelle fonctionnalité.
• fix: vous corrigez un bogue.
• refactoriser: votre changement refactore le code sans corriger un bogue ou ajouter une nouvelle fonctionnalité.
• test: vous apportez des modifications liées aux tests. Par exemple, lorsque vous écrivez des tests avec Jest ou tout autre framework de test que vous choisissez.
• 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: changements qui n’affectent pas la signification du code, comme l’ajout d’espaces blancs, l’absence de points-virgules, etc.
• perf: modifications liées à l’amélioration des performances.
• build: lorsque vous apportez des modifications qui affectent les fichiers de compilation.
• ci: modifications liées à l’intégration continue.
• revert: pour revenir à 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, gardez à l’esprit les éléments suivants :

• Faites en sorte qu’elle soit suffisamment claire et précise pour décrire le commit d’un seul coup d’œil.
• Faites en sorte qu’elle soit brève et concise. L’idéal est de la limiter à 50 caractères ou moins.
• Rédigez-le au présent, même si vous décrivez des modifications déjà effectuées.
• Utilisez l’impératif lors de la rédaction.
• Commencez-la par une majuscule.
• Ne le terminez pas par un point.

Par exemple :

Cet exemple montre comment vous pouvez rédiger la description d’une livraison qui met en œuvre le mode sombre. Il utilise la balise feat car il introduit une nouvelle fonctionnalité.

Corps (facultatif)

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 validation :

• 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 du message 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 du texte. Cela permet à Git de les distinguer.
• Si le commit 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 du commit.

Par exemple :

L’exemple ci-dessus montre un bon message de validation Git pour une fonctionnalité qui ajoute GitHub en tant que 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’une longueur d’environ 72 caractères) et des puces pour des informations supplémentaires.

Pied de page (facultatif)

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 ou le format approprié 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 :

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 d’engagement

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

Le drapeau -m est idéal pour les messages de validation courts, comprenant généralement le type et la description.

Par exemple :

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.

Vous pouvez également rédiger de longs messages de validation dans un fichier texte et utiliser la commande –fichier pour spécifier que les messages de validation sont le contenu du fichier texte.

Par exemple :

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

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 lors de l’exécution d’une commande bare. git commit simple.

Pourquoi vous devez écrire de bons messages de commit

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, une intégration en douceur et le contrôle des versions. Donner la priorité à la qualité des messages de validation améliore les processus de développement et garantit la maintenabilité de la base de code.