Présentation
Dans ce tutoriel, vous suivrez une seule pull request tout au long de l’analyse de Code Quality, du premier commentaire jusqu’à la fusion. Vous apprendrez ce qui suit :
- Comment lire les Code Quality commentaires sur une pull request et distinguer les deux types de remarques.
- Comment utiliser l’étiquette de gravité d’une recherche pour décider de quoi corriger, quoi ignorer et dans quel ordre.
- Comment les choix que vous faites dans une pull request influencent les scores, le backlog et les critères de fusion de votre dépôt.
À la fin, vous aurez résolu tous les problèmes bloquants de l’exemple de pull request et l’aurez fusionnée avec une vérification réussie Code Quality, et vous comprendrez pourquoi vous avez fait chaque choix.
Il s’agit d’un parcours guidé, qui privilégie la compréhension plutôt que la rapidité. Pour connaître les étapes de base pour appliquer une correction automatique ou ignorer un résultat, consultez le guide pratique associé : Correction des problèmes de qualité du code dans une pull request.
Avant de commencer
- Code Quality est activé sur un référentiel auquel vous contribuez. Consultez « Activation de GitHub Code Quality ».
- Le dépôt utilise un langage pris en charge par CodeQL, ce qui permet de générer des résultats et des scores fondés sur des règles. Pour obtenir la liste des langues prises en charge, consultez Qualité du code GitHub.
- Vous avez une pull request ouverte sur la branche par défaut avec au moins un Code Quality résultat à trier. Si vous n’avez pas de pull request prête, vous pouvez suivre l’exemple ci-dessous.
Tout au long de ce tutoriel, nous utiliserons un exemple fil rouge : une pull request qui refactorise une partie du code introduirait plusieurs problèmes de qualité du code dans la branche par défaut si elle était fusionnée en l’état. Une analyse Code Quality a été exécutée automatiquement sur la pull request et a signalé plusieurs problèmes sous forme de commentaires.
Pourquoi la pull request est le meilleur endroit pour corriger un constat
Chaque problème détecté que vous ne résolvez pas au stade de la pull request devient une tâche à traiter dans le backlog de votre dépôt, et la dette technique est souvent plus coûteuse à résorber plus tard que de la traiter dès maintenant. À l’heure actuelle, tant que la pull request est ouverte, le contexte et l’intention du code sont encore bien présents à l’esprit, ce qui vous permet d’évaluer, d’appliquer ou d’écarter plus rapidement et en toute confiance chaque problème détecté ainsi que sa correction automatique.
Résoudre les problèmes détectés au stade de la pull request permet à votre équipe de passer moins de temps à arbitrer entre le travail de remédiation et le développement de fonctionnalités, et d’éviter le surcoût lié à des pull requests supplémentaires uniquement destinées à résorber un backlog.
Étape 1 : Trouvez les commentaires Code Quality sur votre pull request
Lorsque vous ouvrez une demande de tirage, Code Quality exécute deux types d’analyse et publie des résultats sous forme de commentaires. Ouvrez l’onglet Fichiers modifiés de votre demande de tirage et examinez qui a laissé chaque commentaire , l’auteur vous indique quel type de recherche il s’agit.
-
Les résultats basés sur des règles sont publiés par le
github-code-quality[bot]. Code Quality utilise CodeQL pour analyser vos modifications par rapport à un ensemble de règles, et chaque commentaire inclut une correction automatique suggérée. -
Les résultats basés sur l’IA sont publiés par Copilot. Si votre organisation dispose de licences Copilot et que les fonctionnalités d’IA sont activées pour votre entreprise, révision du code Copilot recherche des problèmes de qualité que l’analyse fondée sur des règles risque de ne pas détecter. Ces commentaires incluent également une correction automatique suggérée.
Dans notre exemple, nous allons examiner trois commentaires provenant de github-code-quality[bot], il s’agit donc de constatations fondées sur des règles. Dans votre propre pull request, vous pouvez voir les deux types — identifiez bien lequel est lequel avant d’aller plus loin, car les étiquettes de gravité (étape 2) s’appliquent uniquement aux commentaires fondés sur des règles.
Étape 2 : Lire l’étiquette de gravité pour déterminer ce qui importe
Chaque recherche basée sur des règles comporte une étiquette de github-code-quality[bot] gravité : erreur, avertissement ou note. Recherchez l’étiquette sur l’un des commentaires et vérifiez-la dans ce tableau.
| Sévérité | Definition |
|---|---|
| Error | Indique un problème de gravité élevée susceptible d’entraîner des bogues, des défaillances ou des risques de maintenance majeurs. |
| Avertissement | Indique un problème de gravité modérée qui peut avoir un impact sur la qualité ou la fiabilité du code, mais n’est pas immédiatement critique. |
| Remarque | Indique un problème de faible gravité, une amélioration mineure ou une recommandation. Ces résultats sont utiles pour assurer la maintenance et l’intégrité du code en cours. |
L’étiquette remplit deux fonctions à la fois :
- Il vous indique ce qu’il faut corriger en premier. La gravité reflète l’impact attendu d’une règle dans le code standard. Dans notre exemple, vous commencerez par l’erreur, puis par l’avertissement, et considérerez la note comme une finition facultative.
- Il peut décider si vous pouvez fusionner du tout. Un administrateur de référentiel ou un propriétaire de l’organisation peut configurer Code Quality comme porte de fusion. Par exemple, si le seuil de fusion est « Avertissement et plus », chaque constat de niveau AvertissementetErreur doit être corrigé ou rejeté avant de pouvoir fusionner (les constats de niveau Note ne vous empêcheraient pas de fusionner). De même, un seuil plus strict peut vous obliger à résoudre toutes les conclusions avant la fusion.
Pour vérifier si un contrôle est appliqué, faites défiler jusqu’à la section Vérifications en bas de la pull request. Si vos modifications tombent en dessous du seuil requis, vous verrez une bannière de bloc de fusion : « La fusion est bloquée : les résultats de la qualité du code ont été détectés ».
Dans notre exemple, le seuil est défini sur « Avertissement et plus », de sorte que la bannière est présente : les erreurs et les avertissements bloquent la fusion, et la note ne la bloque pas. Cela vous indique ce que vous devez résoudre avant que cette pull request puisse être fusionnée.
Si la bannière de blocage de fusion n’indique pas de niveau de gravité, vous devez corriger tous les résultats afin de pouvoir fusionner votre pull request.
Étape 3 : Résoudre chaque recherche
Pour chaque recherche, déterminez s’il s’applique à votre code et, le cas échéant, comment le corriger. Cela vous conduit à l’une des trois actions.
| Assessment | Action recommandée | Notes |
|---|---|---|
| La recherche est légitime et le correctif suggéré semble correct | ||
| Appliquer la suggestion de correction automatique | Cliquer sur Appliquer la suggestion ne consomme pas AI credits, et les correctifs automatiques basés sur des règles ne nécessitent pas de licence Copilot. | |
| Le problème est avéré, mais vous souhaitez en corriger plusieurs à la fois, ou le correctif proposé doit être adapté | ||
Déléguer à Copilot— mentionnez @copilot dans un commentaire pour transmettre le travail à l’agent cloud. | ||
| Copilot ajoute la réaction 👀, démarre une nouvelle session d’agent et envoie les correctifs nécessaires à la branche de la pull request | Nécessite une Copilot licence et consomme AI credits. | |
| Le résultat ne s’applique pas, par exemple, il s’agit de code de test, d’un motif intentionnel ou d’un faux positif | Cliquez sur Ignorer la recherche et fournissez une raison | Vous pourrez fusionner votre pull request, mais le problème détecté apparaîtra dans le backlog du dépôt et dans les futures pull requests. |
Appliquez cet exercice à votre propre pull request, en commençant par le plus grave.
Dans notre exemple :
- Les résultats au niveau de l’erreur et de l’avertissement sont des bogues authentiques et les corrections automatiques suggérées semblent raisonnables. Nous appliquons donc les suggestions de correction automatique. Les constats sont résolus et ne sont plus comptabilisés dans le nombre de blocages.
- Un constat de niveau Note met en évidence un schéma mineur dans un utilitaire de test adjacent. C’est intentionnel, donc nous le rejetons avec un motif tel que « Utilisé dans les tests ».
- Il existe plusieurs résultats supplémentaires au niveau de la note. Au lieu de traiter chaque suggestion de correction automatique une par une, nous écrivons en commentaire : «
@copilot, corrige tous les problèmes restants de niveau Note ». Nous suivons la progression de Copilot dans l’onglet Agents du dépôt, et examinons les commits qu’il pousse vers la pull request dès qu’ils sont prêts.
Étape 4 : Vérifiez que votre pull request n’est pas bloquée (facultatif)
Si vous avez bel et bien des problèmes bloquants, une fois que vous avez corrigé ou écarté les problèmes concernés, revenez à la section Checks en bas de la pull request.
Dans notre exemple, une fois les résultats Error et Warning résolus, la bannière de blocage de fusion disparaît. Votre pull request peut maintenant être fusionnée.
Si la bannière est toujours là, cela signifie qu’une recherche au-dessus ou au-dessus de la gravité du blocage est toujours ouverte.
Étape 5 : Résoudre les résultats basés sur l’IA à partir de Copilot
Si votre organisation dispose Copilot de licences et de fonctionnalités IA sont activées pour votre entreprise, vous verrez également les commentaires publiés par Copilot. Il s’agit des résultats basés sur l’IA introduits à l’étape 1, et ils proviennent révision du code Copilot plutôt que de .github-code-quality[bot]
Alors que les résultats basés sur des règles comparent vos modifications à un ensemble fixe de CodeQL règles, révision du code Copilot analyse l’intention de votre code. Il intercepte les problèmes de qualité qui ne sont pas mappés à une règle spécifique. Il s’agit donc d’un complément utile aux commentaires basés sur des règles plutôt qu’à un remplacement pour eux.
Ces résultats ne portent pas d’étiquette de gravité « Erreur », « Avertissement » ou « Remarque ». Étant donné que la porte de fusion que vous avez vue à l’étape 2 compte uniquement la gravité des résultats basés sur des règles, les résultats basés sur l’IA ne bloquent jamais votre demande de tirage en soi. Cela ne les rend pas facultatifs, la résolution de celles-ci dans le contexte est toujours l’endroit optimal pour conserver les problèmes de qualité hors de votre branche par défaut.
Vous résolvez une recherche basée sur l’IA avec les trois options que vous avez utilisées à l’étape 3 :
- Appliquez la suggestion de correction automatique. Chaque commentaire inclut un correctif suggéré. S’il est correct as-is, cliquez sur Valider la suggestion. L’application de la correction automatique ne consomme GitHub AI Creditspas .
- Déléguer à Copilot— mentionnez
@copilotdans un commentaire pour transmettre le travail à l’agent cloud. Copilot ajoute la réaction 👀, démarre une nouvelle session d’agent et pousse les correctifs nécessaires vers la branche de la pull request. Cette option nécessite une Copilot licence et consomme GitHub AI Credits. - Résolvez le commentaire. S’il ne s’applique pas à votre code, cliquez sur Résoudre.
Comment cela s’inscrit dans le reste de votre qualité de code
La pull request que vous venez de valider s’inscrit dans un ensemble plus vaste :
- Scores. Les scores de fiabilité et de maintenance de votre référentiel sont calculés à partir des résultats de la branche par défaut. La résolution des résultats avant la fusion est la façon dont vous empêchez ces scores de dériver. Consultez « Informations de référence sur les métriques et les scores ».
- Backlog. Tout ce que vous ne corrigez pas dans la pull request s’ajoute au backlog des problèmes détectés sur la branche par défaut. Réduire cet arriéré est une discipline à part entière. Consultez « Augmentation du score de qualité du code de votre référentiel ».
- Conformité. Lorsqu’une classe de résultats ne doit pas atteindre la branche par défaut, l’ensemble de règles « Exiger des résultats de qualité du code » aide les administrateurs de référentiel et les propriétaires d’organisations à encoder cette décision en tant que porte de fusion. Consultez « Résolution d’un blocage sur votre requête pull ».
Les équipes les plus efficaces combinent ces trois éléments : un triage et une correction délibérés au stade de la pull request, un travail périodique sur le backlog et des seuils obligatoires au moment de la fusion.
Résolution des problèmes
- Je ne vois aucun Code Quality commentaire. L’analyse peut toujours s’exécuter, vos modifications peuvent ne pas toucher à une langue prise en charge ou vous n’avez pas de résultats. Vérifiez que Code Quality est activé et laissez le temps à la vérification (appelée « CodeQL - Qualité du code ») de se terminer. Consultez « Activation de GitHub Code Quality ».
- Je ne vois que des commentaires de
github-code-quality[bot], jamais de Copilot. Les résultats basés sur l’IA nécessitent des Copilot licences et des fonctionnalités IA activées pour votre entreprise. Sans eux, vous verrez uniquement les résultats basés sur des règles. - Je ne vois pas de corrections automatiques pour les problèmes de qualité du code détectés. La génération d’Autofix consomme GitHub AI Credits. Votre organisation a peut-être épuisé son budget mensuel de AI credits.
- La bannière de bloc de fusion n’est pas effacée. Au moins un constat d’un niveau de gravité bloquant ou supérieur reste ouvert. Si vous ne voyez pas de niveau de gravité défini dans la bannière de bloc de fusion, cela signifie que votre dépôt utilise les seuils de qualité de code les plus stricts, ce qui nécessite que toutes les conclusions soient traitées avant la fusion. Consultez « Résolution d’un blocage sur votre requête pull ».
Conclusion
Dans ce tutoriel, vous avez examiné les commentaires Code Quality sur une pull request, utilisé le niveau de gravité pour prioriser la remédiation et résolu chaque problème détecté de manière réfléchie avant de fusionner votre pull request. En traitant chaque problème détecté et sa correction automatique comme une décision ponctuelle prise dans son contexte, vous avez empêché la dette liée à la qualité du code d’atteindre votre branche par défaut.
Étapes suivantes
- Appliquez la même réflexion à votre backlog existant : Augmentation du score de qualité du code de votre référentiel.
- Découvrez comment les résultats se traduisent en scores afin de mesurer l’impact du travail : Informations de référence sur les métriques et les scores.