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:
- So lesen Sie die Code Quality Kommentare zu Ihrer Pull-Anforderung.
- 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 einer sauberen Code Quality-Prüfung zusammengeführt haben, und Sie werden verstehen, warum Sie jede einzelne 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 einer automatischen Korrektur 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 für den Standardbranch, in dem mindestens ein Code Quality-Befund gesichtet 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 per Refactoring umgestaltet, würde mehrere Probleme bezüglich der Codequalität in den Standardbranch einbringen, wenn er unverändert zusammengeführt 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, wird verwendetCode Quality, CodeQL um Ihre Änderungen anhand einer Reihe von Regeln zu überprüfen und Ergebnisse als Kommentare zu github-code-quality[bot]posten. Jeder Kommentar enthält ein vorgeschlagenes Autofix. Öffnen Sie die Registerkarte "Dateien geändert " Ihrer Pull-Anforderung, um die Ergebnisse zu überprüfen.
In unserem Beispiel sehen wir uns drei Kommentare an github-code-quality[bot]. Notieren Sie sich die Schweregradbezeichnungen auf jedem. In Schritt 2 wird erläutert, was sie bedeuten.
Schritt 2: Lesen Sie die Schweregradbezeichnung, um zu entscheiden, was wichtig ist.
Jeder Gefundene aus github-code-quality[bot] einer Schweregradbezeichnung trägt eine Schweregradbezeichnung – Fehler, Warnung oder Notiz. 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 die Zusammenführung „Warnung und höher“ lautet, muss jeder Befund auf Ebene von Warnung* und *Fehler behoben oder verworfen werden, bevor Sie die Zusammenführung vornehmen 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; 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: Jeden Befund beheben
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 | Wenn Sie auf einen Commit-Vorschlag klicken, wird nicht verwendet AI credits, und Autofixe erfordern Copilot keine 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 (False Positive) 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 Befunde 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. Dies ist beabsichtigt, daher verwerfen wir ihn mit einem Grund wie „In Tests verwendet“.
- Es gibt mehrere zusätzliche Befunde auf Note-Ebene. Anstatt jeden Vorschlag zur automatischen Korrektur einzeln durchzuarbeiten, kommentieren wir: „
@copilot, alle verbleibenden Befunde auf Hinweisebene beheben“. 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 blockierende Befunde haben, kehren Sie, nachdem Sie die relevanten Befunde behoben oder verworfen haben, unten im Pull Request zum Abschnitt Prüfungen zurück.
In unserem Beispiel verschwindet das Banner zur Blockierung der Zusammenführung, sobald die Befunde im Bereich Fehler und Warning behoben sind. Ihr Pull Request kann jetzt zusammengeführt werden.
Wenn das Banner noch angezeigt wird, bedeutet dies, dass ein Befund mit dem Schweregrad „Blockierend“ oder höher noch offen ist.
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.
- Backlog Alles, was Sie im Pull Request nicht beheben, landet im Backlog der Befunde im 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 Standardbranch erreichen darf, hilft der Regelsatz „Ergebnisse zur Codequalität anfordern“ Repository-Admins und Organisationsverantwortlichen dabei, diese Entscheidung als Gate für die Zusammenführung 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, periodische Bearbeitung des Backlogs und Durchsetzen von Schwellenwerten an der Zusammenführungsgrenze.
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 keine automatischen Korrekturen für meine Befunde zur Codequalität. Durch Generierung automatischer Korrekturen werden GitHub AI Credits verbraucht. 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 die zugehörige automatische Korrektur als kleine, kontextbezogene Entscheidungen behandeln, verhindern Sie, dass eine verminderte Codequalität in Ihren Standardbranch gelangt.
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.