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 votre demande de tirage.
- 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 requête 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 requête 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( pull request), Code Quality utilise CodeQL pour analyser vos modifications par rapport à un ensemble de règles et publie les résultats sous forme de commentaires par github-code-quality[bot]. Chaque commentaire inclut une correction automatique suggérée. Ouvrez l’onglet Fichiers modifiés de votre demande de tirage pour examiner les résultats.
Dans notre exemple, nous allons examiner trois commentaires de github-code-quality[bot]. Notez les étiquettes de gravité sur chacune d’elles. L’étape 2 explique ce qu’elles signifient.
Étape 2 : Lire l’étiquette de gravité pour déterminer ce qui importe
Chaque recherche contient 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 requête. 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 | Le fait de cliquer sur Valider ne consomme AI creditspas et les corrections automatiques ne nécessitent pas de Copilot licence. | |
| 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 requête | 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 requête, 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.
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 :
- Résultats. 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 ».
- Carnet de commandes 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 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.