Message de validation Git : Règles, exemples et conventions

Pourquoi un message de validation Git est-il important ?

Un message de validation explique vos modifications à toute personne qui lira le code ultérieurement, y compris vous-même à l'avenir.

Dans trois mois, vous ne vous souviendrez plus pourquoi vous avez refactorisé ce pipeline de données ou pourquoi vous êtes passé de pandas à polars pour une opération spécifique. Votre message de validation constitue le seul enregistrement de votre raisonnement. Sans cela, vous devez vous contenter de deviner ou de parcourir les fils de discussion Slack et les tickets JIRA.

Voici quelques raisons supplémentaires qui expliquent pourquoi les messages de commit Git sont importants.

Les révisions de code sont plus efficaces lorsque les messages de validation sont clairs. Votre réviseur peut examiner le message, en comprendre l'intention et se concentrer sur la conformité de la mise en œuvre. Les messages imprécis obligent les réviseurs à déduire votre raisonnement à partir de la diff seulement.

Le débogage devient également plus facile. Lorsqu'un bug apparaît, vous utiliserez git log ou git blame pour déterminer à quel moment le code problématique a été introduit. Un message tel que « corriger le bug d'authentification » ne fournit aucune information utile. Un message tel que « corriger la vérification de l'expiration du jeton dans le middleware d'authentification » vous indique directement le problème.

La collaboration au sein d'une équipe repose sur un historique lisible. Lorsqu'une personne rejoint votre projet ou reprend là où vous vous êtes arrêté, elle examinera les commits afin de comprendre comment le code a évolué. Des messages clairs transforment votre historique Git en une documentation réellement utile.

En résumé, la rédaction d'un message de validation descriptif prend entre 15 et 30 secondes. Cependant, cela évite des heures de confusion par la suite.

Principes fondamentaux d'un message de commit Git efficace

Les messages de commit efficaces respectent quelques principes simples, rien de plus.

Écrire pour les futurs lecteurs

Votre message de validation n'est pas destiné à vous pour le moment, mais à toute personne qui le lira dans six mois.

Cette personne pourrait être un nouveau membre de l'équipe qui cherche à comprendre pourquoi le code fonctionne d'une certaine manière. Il se peut que ce soit vous, essayant de vous rappeler pourquoi vous avez pris une décision spécifique. Dans tous les cas, ils ne disposeront pas du contexte dont vous disposez aujourd'hui.

Concentrez-vous sur l'intention et le raisonnement, et pas seulement sur ce qui a changé. Le diff indique les modifications apportées. Votre message devrait expliquer pourquoi il a été modifié et quel problème il résout.

Soyez clair et concis

Les messages courts et descriptifs sont plus faciles à parcourir lorsque vous examinez des dizaines de commits.

Un message tel que « ajouter la mise en cache » est imprécis. Un message tel que « Ajouter la mise en cache Redis pour les réponses API » vous informe précisément de ce qui s'est produit. Vous pouvez le consulter à l'adresse git log --oneline et comprendre immédiatement ce que fait le commit.

Votre ligne d'objet doit répondre à la question suivante : que fait ce commit ? Si vous avez besoin de plus de 50 à 60 caractères pour répondre à cette question, il est probable que vous effectuiez trop de modifications à la fois.

Soyez cohérent

La cohérence de votre référentiel rend l'historique prévisible et plus facile à analyser.

Lorsque chaque validation respecte le même format, il est possible de parcourir rapidement l'historique. Vous savez où trouver le type de modification, la portée et la description. Les équipes qui appliquent des formats cohérents peuvent également automatiser des tâches telles que la génération de journaux de modifications ou le filtrage des commits par type.

Veuillez choisir un style et vous y tenir. Si votre équipe utilise des impératifs au présent, veuillez ne pas passer au passé de manière aléatoire.

Veuillez expliquer quoi et pourquoi (et non comment).

Le code démontre comment vous avez résolu le problème. Votre message de validation doit expliquer quel était le problème et pourquoi vous avez choisi cette solution.

Veuillez ne pas écrire « refactoriser load_data() pour utiliser la compréhension de liste à la place de la boucle for ». Veuillez indiquer « accélérer le chargement des données de 40 % pour les fichiers CSV volumineux ». Le premier message décrit la modification du code. Le second explique l'impact.

Veuillez ajouter du contexte lorsque cela aide les futurs lecteurs à comprendre votre décision. Si vous avez envisagé trois approches différentes avant de choisir celle-ci, veuillez le mentionner. S'il existe un rapport de bogue ou une décision de conception connexe, veuillez y faire référence.

La structure d'un message de commit Git

La plupart des messages de commit Git suivent une structure standard en trois parties : ligne d'objet, corps et pied de page.

Objet

La ligne d'objet est un résumé d'une ligne qui apparaît dans les listes d' git log --oneline s et de pull requests.

Veuillez limiter votre réponse à 50 caractères si possible, 72 au maximum. Cette limite garantit que le message s'affiche correctement dans la sortie du terminal et dans l'interface utilisateur de GitHub sans être tronqué. Si votre résumé ne tient pas en 50 caractères, vous essayez probablement de décrire trop de modifications dans un seul commit.

Veuillez utiliser le mode impératif - écrivez « ajouter une fonctionnalité » au lieu de « fonctionnalité ajoutée » ou « ajoute une fonctionnalité ». Considérez cela comme compléter la phrase « Si appliqué, cet engagement permettra de... ». Ainsi, « Si appliqué, ce commit ajoutera la mise en cache Redis » se lit naturellement, tandis que « Si appliqué, ce commit ajoute la mise en cache Redis » ne se lit pas naturellement.

Exemples :

• fix null pointer exception in data loader

• add caching layer for API responses

• remove deprecated pandas functions

Corps (si nécessaire)

Veuillez ignorer le corps pour les modifications simples. Si votre ligne d'objet explique clairement le commit, vous avez terminé.

Veuillez ajouter un corps lorsque vous devez expliquer les raisons de la modification ou fournir un contexte utile aux futurs lecteurs. Veuillez laisser une ligne vide entre l'objet et le corps du message - Git utilise cette ligne pour séparer les deux parties.

Le corps doit répondre à des questions telles que : Quel problème cela résout-il ? Pourquoi avez-vous opté pour cette approche ? Existe-t-il des effets secondaires ou des restrictions ? Avez-vous envisagé d'autres solutions ?

Enveloppez les lignes à 72 caractères afin de garantir la lisibilité du texte dans la sortie du terminal. La plupart des éditeurs de texte peuvent effectuer cette opération automatiquement.

Exemple :

add Redis caching for API responses

API response times were hitting 2-3 seconds for repeated queries.
Added Redis with 5-minute TTL to cache query results. This drops
response time to ~50ms for cached queries.

Considered using in-memory cache but Redis lets us scale horizontally
if needed.

Pied de page (facultatif)

Veuillez utiliser le pied de page pour référencer les problèmes connexes, les demandes d'extraction ou les modifications importantes.

Si votre commit corrige un problème GitHub, veuillez ajouter Fixes #123 ou Closes #456 dans le pied de page. GitHub clôturera automatiquement le ticket lorsque la validation sera fusionnée. Pour les modifications importantes, veuillez ajouter BREAKING CHANGE: suivi d'une description de la nature de la modification et de la procédure de migration.

Exemple :

remove support for Python 3.7

Python 3.7 reached end-of-life in June 2023. This commit drops
support and updates minimum version to Python 3.8.

BREAKING CHANGE: Python 3.7 users must upgrade to 3.8 or later.
Closes #789

Il n'est généralement pas nécessaire d'ajouter un pied de page pour la plupart des commits, sauf lorsque vous créez des liens vers des références externes ou signalez des modifications importantes.

Types courants de messages de commit Git et quand les utiliser

De nombreux projets utilisent des préfixes de type commit pour classer les modifications en un coup d'œil.

Il n'est pas nécessaire de mémoriser une liste stricte d'étiquettes. L'objectif est d'aider les lecteurs à identifier rapidement le type de modification apportée sans avoir à lire l'intégralité du diff.

Voici quatre catégories à prendre en considération :

• Les modifications apportées aux fonctionnalités introduisent de nouvelles fonctionnalités. Veuillez utiliser des préfixes tels que feat: ou add: lorsque vous développez un nouvel élément, qu'il s'agisse d'un nouveau point de terminaison API, d'une fonction de traitement des données ou d'une fonctionnalité destinée aux utilisateurs. Exemple : feat: add CSV export for analysis results.

• Les corrections de bogues permettent de résoudre les problèmes existants. Veuillez utiliser « fix: » lorsque vous corrigez un comportement qui n'a pas fonctionné comme prévu. Cela peut aller d'une exception de pointeur nul à des calculs incorrects dans votre modèle. Exemple : fix: handle missing values in preprocessing pipeline.

• Mises à jour de la documentation: amélioration des commentaires de code, des fichiers README ou de la documentation en ligne. Veuillez utiliser l' docs: lorsque vous ne modifiez pas le fonctionnement du code, mais que vous vous efforcez simplement de mieux l'expliquer. Exemple : docs: add usage examples for data loader class.

• Le refactoring et les travaux de maintenance améliorent la structure du code sans en modifier le comportement. Veuillez utiliser refactor: lorsque vous réorganisez le code afin de le rendre plus clair et plus facile à maintenir. Veuillez utiliser chore: pour les tâches courantes telles que la mise à jour des dépendances ou la modification des configurations de compilation. Exemples : refactor: extract validation logic into separate module ou chore: update pandas to 3.0.0.

Veuillez sélectionner le type qui correspond le mieux à votre changement et passez à l'étape suivante - la cohérence est plus importante que le choix de l'étiquette « parfaite ».

Règles pour rédiger un message de commit Git plus efficace

Voici une liste de règles qui rendront vos messages de validation plus utiles.

• Veuillez limiter la ligne d'objet à 50 caractères. Cela garantit un affichage correct dans git log --oneline, la liste des commits GitHub et la sortie du terminal, sans troncature. Si votre message ne peut être limité à 50 caractères, veuillez viser un maximum de 72 caractères.

• Veuillez utiliser le mode impératif. Veuillez écrire « ajouter une fonctionnalité » au lieu de « fonctionnalité ajoutée » ou « ajoute une fonctionnalité ». Votre ligne d'objet doit compléter la phrase « Si appliqué, cet engagement permettra de... ». Par conséquent, « Si appliqué, ce commit ajoutera la mise en cache » est correct.

• Veuillez séparer l'objet et le corps du message par une ligne vide. Git utilise cette ligne vide pour distinguer le résumé de l'explication détaillée. Sans cela, les outils Git pourraient afficher votre message de manière incorrecte.

• Veuillez omettre le point à la fin de la ligne d'objet. Vous économisez des caractères et l'objet n'est de toute façon pas une phrase complète. Veuillez écrire à l'adresse fix null pointer in loader au lieu de fix null pointer in loader.

• Veuillez mettre une majuscule au premier mot de votre ligne d'objet. Veuillez écrire à l'adresse Add caching for API calls au lieu de add caching for API calls. Cela permet de conserver un historique de vos commits cohérent et professionnel.

• Veuillez utiliser le corps du texte pour expliquer pourquoi, et non quoi. Le diff indique les modifications apportées. Votre organisme devrait expliquer les raisons qui ont motivé ce changement, les autres approches que vous avez envisagées et les compromis que vous avez faits.

• Veuillez limiter le texte du corps à 72 caractères. Cela évite les problèmes de retour à la ligne dans la sortie du terminal et garantit la lisibilité de vos messages de validation dans différents outils.

• Veuillez rendre chaque validation atomique. Une modification logique par validation. Si vous corrigez un bug et refactorisez du code, veuillez les séparer en deux commits avec des messages distincts.

Exemples de messages de commit Git appropriés

Voici des exemples concrets illustrant à quoi ressemblent de bons messages de commit dans différents scénarios.

Une solution simple

fix: handle NaN values in feature engineering

The preprocessing pipeline crashed when encountering NaN values
in the 'age' column. Added fillna() with median imputation before
scaling features.

Cette approche est efficace car elle identifie le problème (plantages NaN), explique où il s'est produit (pipeline de prétraitement, colonne âge) et décrit la solution (imputation médiane).

Une nouvelle fonctionnalité

feat: add model performance tracking to MLflow

Added automatic logging of model metrics, parameters, and artifacts
to MLflow after each training run. This replaces our manual CSV
logging and makes experiment comparison much easier.

Metrics tracked: accuracy, precision, recall, F1 score
Training time also logged for performance monitoring.

Les bonnes validations de fonctionnalités expliquent ce que vous avez développé, pourquoi cela est utile et fournissent tous les détails permettant aux lecteurs de comprendre la portée du travail.

Une refonte

refactor: split data_loader.py into separate modules

Moved dataset classes to datasets.py, transformation logic to
transforms.py, and utility functions to utils.py. The original
file was 800+ lines and hard to navigate.

No behavior changes - all tests still pass.

Les messages de refactorisation doivent indiquer clairement que vous n'avez pas modifié les fonctionnalités, mais uniquement la structure. La mention « tous les tests sont toujours réussis » rassure les évaluateurs.

Une mise à jour de la documentation

docs: add examples for custom loss functions

Previous documentation showed only built-in loss functions.
Added three examples: weighted cross-entropy, focal loss, and
custom regression loss with L1 regularization.

Each example includes code and explanation of when to use it.

Les commits de documentation doivent expliquer ce que vous avez documenté et pourquoi cela était nécessaire.

Référencer un problème ou un ticket

fix: prevent memory leak in batch processing

Large datasets caused memory usage to grow unbounded during batch
processing. The issue was holding references to processed batches
in the results list.

Changed to yield results instead of accumulating them in memory.
Memory usage now stays constant regardless of dataset size.

Fixes #247

Lorsque vous faites référence à un problème, veuillez inclure suffisamment de contexte pour que quelqu'un puisse comprendre la solution sans avoir à cliquer sur le ticket. La commande « Fixes #247 » en bas indique à GitHub de fermer automatiquement le ticket lorsque cette validation est fusionnée.

Tous les exemples suivent le même schéma : commencez par indiquer ce qui a changé, expliquez pourquoi, ajoutez des informations contextuelles utiles aux futurs lecteurs et faites référence à des problèmes connexes, le cas échéant.

Les commits conventionnels en tant que norme pour les messages de commit Git

Les commits conventionnels constituent un format populaire qui structure les messages de commit grâce à un modèle de préfixe simple.

Format de base

Le format se présente comme suit : type(scope): description.

Le type décrit le type de modification que vous effectuez : feat pour les fonctionnalités, fix pour les corrections de bogues, docs pour la documentation, refactor pour la restructuration du code, etc. La portée est facultative et précise quelle partie du code a été modifiée, par exemple (auth) ou (api). La description de l' explique ce que vous avez réalisé.

Exemples :

feat(api): add endpoint for batch predictions
fix(auth): prevent token expiration edge case
docs(readme): add installation instructions for Windows
refactor(data): extract validation logic to separate module

Veuillez noter qu'il s'agit d'une convention et non d'une exigence. Git ne se soucie pas de l'utilisation de ce format. Il s'agit principalement d'une décision prise en équipe concernant la manière de structurer vos messages afin d'assurer leur cohérence et de choisir les outils appropriés.

Quand les commits conventionnels sont utiles

Les équipes qui automatisent les processus de publication tirent le meilleur parti des commits conventionnels.

Les outils peuvent analyser l'historique de vos commits et générer automatiquement des journaux de modifications. Lorsque vous marquez une version, l'outil analyse les commits depuis la dernière version, les regroupe par type (feat, fix, docs) et crée un journal des modifications formaté. Cela évite le travail manuel consistant à suivre les modifications entre les versions.

Les commits conventionnels prennent également en charge l'automatisation du versionnage sémantique. Si toutes vos validations depuis la dernière version sont corrigées, l'outil augmente la version du correctif (1.2.3 → 1.2.4). Si vous avez ajouté des fonctionnalités, cela modifie la version mineure (1.2.3 → 1.3.0). Les modifications importantes entraînent un changement majeur de version (1.2.3 → 2.0.0).

Cependant, si votre équipe n'utilise pas de versions automatisées ou de génération de journal des modifications, les commits conventionnels pourraient s'avérer excessifs. Il est important de noter que cette structure est davantage conçue pour les machines que pour les humains.

Erreurs courantes à éviter dans les messages de commit Git

Même les développeurs expérimentés commettent parfois des erreurs lorsqu'ils rédigent des messages de validation, mais cela relève davantage de la négligence que d'un manque de connaissances.

Voici quelques erreurs à éviter.

Messages imprécis ou génériques

Les messages tels que « corriger le bug » ou « mettre à jour le code » n'apportent aucune information utile aux futurs lecteurs.

Lorsque vous recherchez une modification spécifique dans git log, vous parcourez des dizaines de commits. Un message indiquant « corriger le bug » vous oblige à ouvrir le diff et à lire le code pour comprendre ce qui a été corrigé. Un message indiquant « corriger le pointeur nul dans le prétraitement des données » vous permet de déterminer immédiatement s'il s'agit de la validation que vous recherchez.

Les messages génériques font perdre du temps à tout le monde. Si vous ne vous souvenez pas suffisamment bien de ce que vous avez modifié pour rédiger un message spécifique, il est préférable de ne pas encore valider.

Mélanger des modifications non liées

Chaque commit doit contenir une seule modification logique.

Lorsque vous corrigez un bug et refactorisez du code non lié dans le même commit, vous compliquez les revues de code et rendez l'git bisect e inutile. Si cette validation introduit une régression, il sera nécessaire de déterminer quelle partie de la modification en est à l'origine. Si vous souhaitez revenir uniquement la correction de bug, ils ne peuvent pas le faire : ils annuleront également la refonte.

Il est recommandé de toujours diviser les modifications en commits distincts. Veuillez corriger le bug dans un commit, et procéder à la refonte dans un autre. Chaque validation doit pouvoir être annulée indépendamment sans perturber le code source.

Si vous avez déjà fusionné les modifications localement, veuillez utiliser git add -p pour mettre en attente certaines parties des fichiers séparément et les valider par blocs logiques.

Laisser des messages sur les travaux en cours

Les commits accompagnés de messages tels que « WIP » ou « temp fix » sont acceptables localement, mais ne devraient pas être intégrés à la branche principale. branche principale.

Avant de fusionner votre branche de fonctionnalité, veuillez nettoyer votre historique de commits. Squash Les commits WIP sont transformés en commits significatifs accompagnés de messages appropriés. Veuillez reformuler « asdf » et « essayer quelque chose » en descriptions qui expliquent ce que vous avez réellement fait.

Veuillez utiliser git rebase -i pour regrouper les commits, réécrire les messages et réorganiser les modifications avant de les publier. Votre équipe devrait pouvoir consulter un historique clair des modifications apportées et des raisons qui les ont motivées, sans avoir à examiner votre processus de débogage.

Meilleures pratiques pour les équipes utilisant les messages de validation Git

Si votre équipe souhaite rendre l'historique Git véritablement utile, la cohérence est essentielle. Voici quelques bonnes pratiques à suivre.

Veuillez convenir rapidement d'un style commun. Veuillez déterminer si vous utiliserez des commits conventionnels, un format personnalisé ou simplement un ensemble de règles de base. Veuillez choisir une approche et l'appliquer de manière cohérente à l'ensemble de l'équipe. Lorsque la moitié de vos commits indiquent « feat : ajout d'une fonctionnalité » et l'autre moitié « Ajout d'une nouvelle fonctionnalité », votre historique devient plus difficile à analyser et l'automatisation peut être perturbée.

Le style importe moins que le fait que tout le monde le suive. Certaines équipes préfèrent l'impératif au présent (« ajouter une fonctionnalité »), d'autres utilisent le passé (« fonctionnalité ajoutée »). Les deux fonctionnent bien s'ils sont appliqués de manière cohérente.

Veuillez consigner vos conventions dans un endroit facilement accessible. Veuillez ajouter un fichier CONTRIBUTING.md à votre dépôt expliquant le format de vos messages de commit avec des exemples. Veuillez l'inclure dans les documents d'intégration destinés aux nouveaux membres de l'équipe. Lorsqu'une personne demande « Comment dois-je formater cette validation ? », veuillez la diriger vers la documentation plutôt que de lui fournir une nouvelle explication.

Votre documentation doit couvrir le format de base que vous utilisez, quand ajouter un corps au message plutôt que de se limiter à l'objet, comment référencer les problèmes ou les tickets, et quelques exemples concrets tirés de votre dépôt.

Veuillez utiliser les messages de validation lors des révisions de code. Des messages de commit pertinents permettent d'accélérer et de mieux cibler les révisions des pull requests. Les réviseurs peuvent consulter les messages de validation pour comprendre la progression des modifications avant de se plonger dans le code.

Lors de la révision, veuillez vérifier les messages de validation de la même manière que vous vérifiez le code. Si un message est imprécis ou susceptible d'induire en erreur, veuillez demander qu'il soit réécrit avant de le fusionner. Une PR avec des commits clairs est plus facile à examiner, plus facile à annuler si nécessaire et plus facile à comprendre par la suite.

Conclusion

Un message de validation clair prend 30 secondes à rédiger, mais permet d'éviter des heures de confusion par la suite.

Considérez votre historique de commits comme une documentation qui accompagne votre code. Lorsque vous écrivez « corriger le bug » au lieu de « corriger le pointeur nul dans le prétraitement des données », vous faites perdre du temps à tous ceux qui liront cette validation ultérieurement, y compris vous-même.

Veuillez traiter vos messages de validation comme du code. Si vous ne soumettriez pas de code négligé et non commenté en production, veuillez également éviter de soumettre des messages de validation négligés. Veuillez utiliser le mode impératif, limiter les lignes d'objet à moins de 50 caractères, expliquer le pourquoi dans le corps du message si nécessaire et rendre chaque commit atomique.

Vous savez désormais comment rédiger des messages de validation pertinents. Pour approfondir vos compétences, nous vous invitons à vous inscrire à notre cours Git intermédiaire.