Comment rédiger un message de validation Git 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 validez des modifications dans vos fichiers de projet, vous devez fournir un message expliquant ce qu'elles font ou pourquoi vous les avez apportées.

Les messages de validation servent de forme de documentation et de communication. Ils jouent un rôle crucial dans le maintien d'un historique de version clair et organisé d'un projet. Apprenez à rédiger de bons messages de commit 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.

Ainsi:

: 
[corps facultatif]
[pied de page facultatif]

Taper

Le type décrit le type de modification apportée au commit actuel. Vous pouvez utiliser n'importe quel système adapté à votre situation. 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é.
• réparer: vous corrigez un bug.
• refactoriser: votre modification refactorise le code sans corriger de bogue ni ajouter de nouvelle fonctionnalité.
• test: vous apportez des modifications liées aux tests. Par exemple, lorsque vous écrire des tests avec Jest ou n'importe lequel autre cadre de test tu choisis.
• corvée: modifications sans rapport avec un correctif, une fonctionnalité ou un test. Par exemple, mettre à jour les dépendances.
• documents: 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: modifications liées à l'amélioration des performances.
• construire: lorsque vous apportez des modifications qui affectent les fichiers de construction.
• ci: changements liés à l'intégration continue.
• revenir: lors du retour à un commit précédent.

Description

La « description » d'un message de validation est un résumé concis et descriptif des modifications apportées à la validation. Il sert de titre qui capture l'essence du commit.

Lors de la rédaction de la description, gardez à l'esprit les points suivants :

• Soyez suffisamment clair et précis pour décrire le commit en un coup d'œil.
• Soyez bref et concis. Idéalement, il serait préférable de le limiter à 50 caractères ou moins.
• Écrivez-le au présent, même si vous décrivez des changements déjà apportés.
• Utilisez l'humeur impérative en l'écrivant.
• Commencez-le par une majuscule.
• Ne le terminez pas par un point.

Par exemple:

exploit: implémenter le basculement en mode sombre pour la page d'accueil

Cet exemple montre comment vous pouvez écrire la description d'un commit qui implémente le mode sombre. Il utilise le exploit type car il introduit une nouvelle fonctionnalité.

Corps (facultatif)

La section du corps d'un message de validation fournit des détails et un contexte supplémentaires sur les modifications apportées à la validation. Vous n'aurez pas toujours besoin d'un corps, mais cela peut aider à fournir plus d'informations, à expliquer le raisonnement d'un changement ou à décrire des considérations techniques.

Voici quelques points à noter lors de l'écriture de la section body d'un message de validation :

• Git n'enveloppe jamais le texte automatiquement, donc enveloppez-le manuellement à 72 caractères lorsque vous écrivez le corps. 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 le changement, pourquoi vous avez fait le changement et le raisonnement derrière votre changement.
• Vous devez laisser une ligne vide entre la ligne de description et le corps. Cela permet à Git de les distinguer.
• Si la validation introduit plusieurs modifications 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:

feat: Ajouter GitHub en tant que fournisseur OAuth
Intégrez GitHub en tant que fournisseur OAuth pour permettre une 
authentification avec les comptes GitHub.
- Implémenter le flux d'authentification OAuth avec l'API GitHub
- Configurez les points de terminaison et les paramètres nécessaires pour l'authentification GitHub
- Mise à jour de l'interface utilisateur pour inclure l'option de connexion GitHub

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

La section de pied de page d'un message de validation est une partie facultative qui fournit des informations supplémentaires ou des métadonnées liées à la validation. Il est généralement placé après la section du corps, séparé par une ligne vierge. Le pied de page peut inclure divers types d'informations, telles que 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 garantit que les références sont correctement reconnues et liées.

Par exemple:

feat: Ajouter GitHub comme fournisseur OAuth
Intégrez GitHub en tant que fournisseur OAuth pour permettre une 
authentification avec les comptes GitHub.
- Implémenter le flux d'authentification OAuth avec l'API GitHub
- Configurez les points de terminaison et les paramètres nécessaires pour l'authentification GitHub
- Mise à jour de l'interface utilisateur pour inclure l'option de connexion GitHub
Résout: #123
Voir aussi: #456, #789

Le pied de page fait référence au problème connexe #123 et mentionne d'autres problèmes connexes #456 et #789 pour un contexte supplémentaire.

Ajout du message de validation

Vous pouvez écrire des messages de validation en utilisant le -m drapeau suivi du message de validation entre guillemets (facultatif mais recommandé).

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

Par exemple:

git commit -m "corvée: changer linter en ESlint"

Cependant, lorsque votre message de commit nécessite plus de détails, comme un corps et un pied de page, vous feriez mieux d'écrire le commit dans un éditeur de texte ou un IDE.

Alternativement, vous pouvez écrire de longs messages de validation dans un fichier texte et utiliser le --déposer flag pour spécifier les messages de validation comme contenu du 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 validation.

Vous pouvez également dire à git d'ouvrir votre éditeur par défaut pour écrire un message plus long. Si vous avez défini la variable d'environnement GIT_EDITOR ou EDITOR, git ouvrira ce programme lorsque vous exécuterez un simple git commet commande.

Pourquoi devriez-vous écrire de bons messages de validation

Rédiger de bons messages de validation est crucial pour une collaboration efficace et la maintenance du code. Des messages clairs et descriptifs facilitent la compréhension, le débogage et les révisions 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 fluide et prennent en charge le contrôle des versions. Donner la priorité aux messages de validation de qualité améliore les processus de développement et garantit la maintenabilité de la base de code.