Einführung
In diesem Tutorial verfolgen Sie einen einzelnen Pull Request im Verlauf der Analyse von Code Quality, vom ersten Kommentar an bis zum Merge. Sie lernen Folgendes:
- Wie man die Kommentare zu Code Quality in einem Pull Request liest und die beiden Arten von Hinweisen unterscheidet.
- Wie man die Schweregradkennzeichnung eines Ergebnisses verwendet, um zu entscheiden, was behoben, was verworfen und in welcher Reihenfolge vorgegangen werden soll.
- Wie sich Ihre Entscheidungen in einem Pull Request auf die Bewertungen, den Backlog und die Merge-Gates Ihres Repositorys auswirken.
Am Ende werden Sie jeden blockierenden Befund im Beispiel-Pull-Request behoben und ihn mit einem sauberen Code Quality Check gemergt haben, und Sie werden verstehen, warum Sie jede Entscheidung getroffen haben.
Dies ist eine geführte Einführung, daher steht das Verständnis mehr im Vordergrund als das Tempo. Informationen zu den grundlegenden Schritten zum Übernehmen eines Autofixes oder zum Verwerfen eines Befunds finden Sie in der ergänzenden Anleitung: Beheben von Erkenntnissen zur Codequalität in einem Pull Request.
Bevor du anfängst
- Code Quality ist für ein Repository aktiviert, an dem Sie mitwirken. Siehe Aktivieren von GitHub Code Quality.
- Das Repository verwendet eine von CodeQL unterstützte Sprache, damit regelbasierte Erkenntnisse und Bewertungen generiert werden. Eine Liste der unterstützten Sprachen finden Sie unter GitHub-Codequalität.
- Sie haben einen offenen Pull Request gegen den Standard-Branch, in dem mindestens ein Code Quality Befund triagiert werden muss. Wenn Sie keine Pullanforderung bereit haben, können Sie dem folgenden Beispiel folgen.
In diesem Tutorial verwenden wir durchgehend dasselbe Beispiel: Ein Pull Request, der einen Teil des Codes refaktoriert, würde mehrere Probleme mit der Codequalität in den Standard-Branch einbringen, wenn er unverändert gemergt wird. Ein Code Quality Scan wurde automatisch für den Pull Request ausgeführt und hat mehrere Befunde in Form von Kommentaren gemeldet.
Warum der Pull Request der beste Ort ist, um einen Befund zu beheben
Jedes Problem, das Sie nicht schon in der Pull-Request-Phase beheben, wird zu einer Aufgabe im Backlog Ihres Repositorys, und technische Schulden sind später oft teurer abzubauen, als sie jetzt zu beheben. Gerade jetzt, solange der Pull Request noch offen ist, sind Ihnen der Kontext und der Zweck des Codes noch präsent, sodass jeder Fund und seine automatische Korrektur schneller bewertet, angewendet oder mit gutem Gewissen verworfen werden können.
Wenn Befunde bereits im Pull-Request-Stadium behoben werden, muss Ihr Team weniger Zeit darauf verwenden, Behebungsaufwand gegenüber der Feature-Entwicklung abzuwägen, und vermeidet den Zusatzaufwand durch weitere Pull Requests, die nur dem Abbau eines Backlogs dienen.
Schritt 1: Suchen Sie die Code Quality Kommentare in Ihrem Pull Request
Wenn Sie eine Pull-Anforderung öffnen, Code Quality werden zwei Arten von Analyseergebnissen ausgeführt und Ergebnisse als Kommentare veröffentlicht. Öffnen Sie den Reiter Dateien geändert Ihres Pull-Requests und sehen Sie nach, wer den jeweiligen Kommentar hinterlassen hat – am Verfasser erkennen Sie, um welche Art von Hinweis es sich handelt.
-
Regelbasierte Erkenntnisse werden von der
github-code-quality[bot]veröffentlicht. Code Quality verwendet CodeQL, um Ihre Änderungen anhand eines Regelsatzes zu prüfen, und jeder Kommentar enthält einen Vorschlag für eine automatische Korrektur. -
KI-gestützte Erkenntnisse werden von Copilot veröffentlicht. Wenn Ihre Organisation über Copilot Lizenzen verfügt und KI-Funktionen für Ihr Unternehmen aktiviert sind, sucht Copilot Codeüberprüfung nach Qualitätsproblemen, die die regelbasierte Analyse möglicherweise übersieht. Diese Kommentare enthalten auch ein vorgeschlagenes Autofix.
In unserem Beispiel schauen wir uns drei Kommentare an, die von github-code-quality[bot] stammen, es handelt sich also um regelbasierte Erkenntnisse. In Ihrer eigenen Pull-Anforderung werden möglicherweise beide Typen angezeigt– beachten Sie, welches ist, bevor Sie fortfahren, da Schweregradbezeichnungen (Schritt 2) nur für die regelbasierten Kommentare gelten.
Schritt 2: Lesen Sie die Schweregradbezeichnung, um zu entscheiden, was wichtig ist.
Jeder regelbasierte Befund von github-code-quality[bot] ist mit einer Schweregradbezeichnung versehen – Fehler, Warnung oder Hinweis. Suchen Sie die Bezeichnung in einem der Kommentare, und überprüfen Sie sie anhand dieser Tabelle.
| Severity | Definition |
|---|---|
| Error | Gibt ein Problem mit hohem Schweregrad an, das wahrscheinlich Bugs, Ausfälle oder erhebliche Wartungsrisiken verursacht. |
| Warnung | Gibt ein Problem mit mittlerem Schweregrad an, das sich auf die Codequalität oder Zuverlässigkeit auswirken kann, aber nicht sofort kritisch ist. |
| Hinweis | Gibt ein Problem mit geringem Schweregrad, geringfügige Verbesserung oder Empfehlung an. Diese Ergebnisse sind nützlich für die fortlaufende Codeintegrität und -wartung. |
Die Beschriftung erfüllt für Sie auf einmal zwei Funktionen:
- Es teilt Ihnen mit, was Zuerst behoben werden soll. Der Schweregrad spiegelt die erwarteten Auswirkungen einer Regel im typischen Code wider. In unserem Beispiel beginnen Sie mit dem Fehler, dann mit der Warnung und betrachten den Hinweis als optionalen Feinschliff.
- Es kann entscheiden, ob Sie überhaupt zusammenführen können. Ein Repositoryadministrator oder Organisationsinhaber kann Code Quality als ein Merge-Gate konfigurieren. Wenn beispielsweise der Schwellenwert für das Zusammenführen auf „Warnung und höher“ festgelegt ist, muss jeder Befund auf Warnungs*- und*** Fehlerstufe** behoben oder verworfen werden, bevor Sie zusammenführen können (Hinweis-Befunde würden Sie nicht am Zusammenführen hindern). Ebenso kann ein strengerer Schwellenwert erforderlich sein, um alle Ergebnisse vor dem Zusammenführen aufzulösen.
Um zu sehen, ob eine Sperre aktiv ist, scrollen Sie unten im Pull Request zum Abschnitt Prüfungen. Wenn Ihre Änderungen den erforderlichen Schwellenwert unterschreiten, wird Ihnen ein Hinweisbanner angezeigt: „Die Zusammenführung ist blockiert: Es wurden Probleme mit der Codequalität erkannt.“
In unserem Beispiel ist das Gate auf „Warnung und höher“ eingestellt, sodass das Banner angezeigt wird: der Fehler und die Warnung blockieren die Zusammenführung, und der Hinweis tut dies nicht. Das teilt Ihnen mit, was Sie löschen müssen, bevor diese Pullanforderung zusammengeführt werden kann.
Wenn im Merge-Block-Banner keine Schweregradstufe angegeben ist, müssen Sie alle Befunde beheben, um Ihren Pull Request zu mergen.
Schritt 3: Auflösen der einzelnen Suche
Entscheiden Sie bei jedem Befund, ob er auf Ihren Code zutrifft und, falls ja, wie er behoben werden kann. Das führt Sie zu einer von drei Aktionen.
| Assessment | Empfohlene Maßnahme | Hinweise |
|---|---|---|
| Der Befund ist berechtigt und die vorgeschlagene Korrektur erscheint korrekt. | ||
| Anwenden des AutoFix-Vorschlags | Durch Klicken auf Vorschlag übernehmen wird AI credits nicht verbraucht, und regelbasierte automatische Korrekturen erfordern keine Copilot-Lizenz. | |
| Der Befund ist tatsächlich vorhanden, aber Sie möchten mehrere Probleme gleichzeitig beheben, oder die vorgeschlagene Behebung muss angepasst werden. | ||
Delegieren an Copilot– Erwähnen Sie @copilot in einem Kommentar, um die Arbeit an den Cloud-Agent zu übergeben. | ||
| Copilot reagiert mit 👀, startet eine neue Agent-Sitzung und überträgt die erforderlichen Korrekturen in den Branch des Pull Requests | Erfordert eine Copilot Lizenz und verwendet AI credits. | |
| Der Befund trifft nicht zu, wenn es sich beispielsweise um Testcode, ein beabsichtigtes Muster oder einen Fehlalarm handelt. | Klicken Sie auf „Ergebnis verwerfen“ und geben Sie einen Grund an. | Sie können Ihren Pull Request zusammenführen, aber der Befund wird im Repository-Backlog und in zukünftigen Pull Requests angezeigt. |
Wenden Sie das Gelernte auf Ihren eigenen Pull Request an und arbeiten Sie dabei in der Reihenfolge des Schweregrads.
In unserem Beispiel:
- Die Ergebnisse auf Fehler- und Warnebene sind echte Fehler, und die vorgeschlagenen Autofixe sehen vernünftig aus, sodass wir die AutoFix-Vorschläge anwenden. Die Ergebnisse werden behoben und nicht mehr in der Anzahl der Blockierungen mitgezählt.
- Ein Befund auf Hinweis-Ebene weist auf ein geringfügiges Muster in einem benachbarten Testhilfsprogramm hin. Es ist beabsichtigt, daher schließen wir es mit einem Grund wie "In Tests verwendet".
- Es gibt mehrere zusätzliche Befunde auf Note-Ebene. Anstatt jeden AutoFix-Vorschlag einzeln durchzuarbeiten, kommentieren wir Folgendes: "
@copilotBeheben Sie alle verbleibenden Ergebnisse auf Note-Level". Wir verfolgen den Fortschritt von Copilot im Tab Agents des Repositorys und überprüfen die Commits, die es in den Pull Request pusht, sobald sie bereitstehen.
Schritt 4: Bestätigen Sie, dass Ihre Pullanforderung entsperrt ist (optional)
Wenn Sie wirklich blockierende Befunde haben, kehren Sie, nachdem Sie die relevanten Befunde behoben oder verworfen haben, unten im Pull Request zum Prüfungen-Abschnitt zurück.
In unserem Beispiel verschwindet das Banner zur Zusammenführungssperre, sobald die Erkenntnisse Error und Warning behoben sind. Ihr Pull Request kann jetzt zusammengeführt werden.
Wenn das Banner noch angezeigt wird, bedeutet das, dass ein Befund mit dem Schweregrad „Blockierend“ oder höher noch offen ist.
Schritt 5: Beheben Sie die KI-gestützten Erkenntnisse von Copilot
Wenn Ihre Organisation über Copilot Lizenzen verfügt und KI-Funktionen für Ihr Unternehmen aktiviert sind, sehen Sie auch Kommentare von Copilot. Dies sind die KI-basierten Erkenntnisse , die in Schritt 1 eingeführt wurden, und sie stammen Copilot Codeüberprüfung von statt von github-code-quality[bot].
Während die regelbasierten Ergebnisse Ihre Änderungen anhand eines festen Satzes von CodeQL Regeln abgleichen, erschließt Copilot Codeüberprüfung die Absicht Ihres Codes. Es erfasst Qualitätsprobleme, die keiner bestimmten Regel zugeordnet sind, daher ist es eine nützliche Ergänzung zu den regelbasierten Kommentaren und nicht zu einem Ersatz für sie.
Diese Ergebnisse tragen keine Schweregradbezeichnung von "Fehler", "Warnung" oder "Hinweis". Da das Merge-Gate, das Sie in Schritt 2 gesehen haben, nur den Schweregrad von regelbasierten Ergebnissen berücksichtigt, blockieren KI-gestützte Ergebnisse Ihren Pull Request für sich genommen nie. Das macht sie nicht optional; sie im Kontext aufzulösen ist nach wie vor der beste Weg, um Qualitätsprobleme von Ihrem Standard-Branch fernzuhalten.
Sie lösen eine KI-gestützte Suche mit den gleichen drei Optionen auf, die Sie in Schritt 3 verwendet haben:
- Wenden Sie den AutoFix-Vorschlag an. Jeder Kommentar enthält einen vorgeschlagenen Fix. Wenn sie in dieser Form korrekt ist, klicken Sie auf Commit vorschlagen. Das Anwenden von Autofix verbraucht GitHub AI Credits nicht.
- Delegieren an Copilot– Erwähnen Sie
@copilotin einem Kommentar, um die Arbeit an den Cloud-Agent zu übergeben. Copilot reagiert mit 👀, startet eine neue Agent-Sitzung und pusht die erforderlichen Korrekturen an die Verzweigung der Pullanforderung. Diese Option erfordert eine Copilot Lizenz und verbraucht GitHub AI Credits. - Auflösen des Kommentars. Wenn sie nicht auf Ihren Code angewendet wird, klicken Sie auf "Auflösen".
Wie dies mit dem Rest Ihres Codes in Bezug auf die Codequalität zusammenhängt
Die soeben gelöschte Pull-Anforderung ist Teil eines größeren Bilds:
- Resultate. Die Bewertungen für die Zuverlässigkeit und Wartbarkeit Ihres Repositorys werden aus den Ergebnissen im Standard-Branch berechnet. Indem Sie Befunde vor dem Zusammenführen beheben, verhindern Sie, dass diese Werte abdriften. Siehe Referenz für Metriken und Bewertungswerte.
- Rückstand. Alles, was Sie im Pull Request nicht beheben, landet im Backlog der Befunde auf dem Standardbranch. Das Zurückarbeiten dieses Rückstands ist eine Eigene Disziplin. Siehe Erhöhen der Codequalitätsbewertung Ihres Repositorys.
- Beachtung. Wenn eine Kategorie von Befunden wirklich nicht den Standard-Branch erreichen darf, hilft das Regelset „Codequalitätsergebnisse anfordern“ Repository-Administratoren und Organisationsinhabern dabei, diese Entscheidung als Merge-Schranke festzulegen. Siehe Auflösen eines Blocks in Ihrer Pullanforderung.
Die leistungsfähigsten Teams kombinieren alle drei: gezielte Triage und Behebung in der Pull-Request-Phase, regelmäßige Arbeit am Backlog und verbindliche Schwellenwerte an der Merge-Grenze.
Problembehandlung
- Ich sehe Code Quality keine Kommentare. Der Scan wird möglicherweise noch ausgeführt, Ihre Änderungen berühren möglicherweise keine unterstützte Sprache, oder Sie haben keine Ergebnisse. Vergewissern Sie sich, dass Code Quality aktiviert ist, und geben Sie der Prüfung (genannt „CodeQL – Codequalität“) Zeit, abgeschlossen zu werden. Siehe Aktivieren von GitHub Code Quality.
- Ich sehe nur Kommentare aus
github-code-quality[bot], nie aus Copilot. KI-basierte Ergebnisse erfordern Copilot Lizenzen und KI-Features, die für Ihr Unternehmen aktiviert sind. Ohne sie werden nur regelbasierte Ergebnisse angezeigt. - Ich sehe keine automatischen Korrekturen für meine Befunde zur Codequalität. Die Autofix-Generierung verbraucht GitHub AI Credits. Möglicherweise hat Ihre Organisation ihr monatliches Budget von AI credits ausgeschöpft.
- Das Merge-Block-Banner lässt sich nicht entfernen. Mindestens ein Befund mit dem Schweregrad „Blockierend“ oder höher ist noch offen. Wenn im Banner des Merge-Blocks kein Schweregrad definiert ist, bedeutet dies, dass Ihr Repository die strengsten Schwellenwerte für die Codequalität verwendet, die erfordern, dass alle Befunde behoben werden, bevor zusammengeführt werden kann. Siehe Auflösen eines Blocks in Ihrer Pullanforderung.
Fazit
In diesem Tutorial haben Sie die Code Quality Kommentare zu einem Pull Request durchgearbeitet, den Schweregrad zur Priorisierung der Behebung verwendet und jeden Befund bewusst behoben, bevor Sie Ihren Pull Request zusammengeführt haben. Indem Sie jeden Befund und den zugehörigen Autofix als kleine, kontextbezogene Entscheidungen behandeln, haben Sie verhindert, dass Qualitätsschulden im Code in Ihren Standard-Branch gelangen.
Nächste Schritte
- Wenden Sie dasselbe Denken auf Ihren vorhandenen Backlog an: Erhöhen der Codequalitätsbewertung Ihres Repositorys.
- Erfahren Sie, wie Ergebnisse in Bewertungen übersetzt werden, damit Sie die Auswirkungen der Arbeit messen können: Referenz für Metriken und Bewertungswerte.