KI-generierten Code in Pull Requests stapeln

Große Pull Requests sind schwierig zu überprüfen und führen zu Engpässen, insbesondere wenn KI Ihnen hilft, ein hohes Codevolumen in kurzer Zeit zu generieren. Die Qualität der Überprüfung verschlechtert sich auch, wenn die Größe des Pull Requests zunimmt. Prüfer können das Ergebnis nur überfliegen, Probleme übersehen oder den Pull Request liegen lassen, bis er veraltet und Merge-Konflikte entstehen.

Gestapelte Pull Requests halten große Codeänderungen überprüfbar.

Ein Stapel ist eine Reihe von Pullanforderungen im selben Repository, in dem jede Pullanforderung auf die Verzweigung der Pullanforderung darunter ausgerichtet ist und eine geordnete Kette bildet, die in einer einzelnen Verzweigung landet, in der Regel Ihre Hauptzweige. Anstelle einer großen Pullanforderung erhalten Sie eine Reihe kleinerer Pullanforderungen. Da jede Pullanforderung über einen eigenen diff mit Relevanz verfügt, können Teamkollegen jede Ebene unabhängig überprüfen und genehmigen.

In diesem Lernprogramm erfahren Sie, wie Sie gestapelte Pull Requests mit Agents verwenden, um ein Feature in einzeln überprüfbaren Ebenen zu erstellen. In unserem Beispiel überlegen wir, wie Sie einer App eine Benutzerauthentifizierung hinzufügen. Wir verwenden GitHub Copilot CLI und die gh-stack Agentenfähigkeit.

Voraussetzungen

Um die gh-stack Fähigkeit mit einem Agent zu verwenden, müssen Sie zuerst GitHub CLI und die gh-stack CLI-Erweiterung installieren. Sie benötigen Folgendes:

• GitHub CLI (gh) 2.90.0 oder höher und Git 2.20 oder höher.
  • Authentifizieren Sie sich bei GitHub CLI mit gh auth login.
• Ein GitHub Repository, an das Sie pushen können.
• GitHub Copilot CLI ist installiert und angemeldet.

In GitHub CLI, installieren Sie die gh-stack Erweiterung und den Skill.

gh extension install github/gh-stack
gh skill install github/gh-stack

1. Entwerfen Sie einen Stack, bevor Sie Code generieren

Ein guter Stack ist wie das Bauen eines Hauses: mit einem starken Fundament beginnen, die Wände einrahmen, die Verkabelung installieren und dann den Trockenbau fertigstellen. Jede Ebene baut auf der darunterliegenden auf. Am Ende sollte ein Prüfer in der Lage sein, die Pull Requests von unten nach oben zu lesen und nachvollziehen zu können, wie das Feature Gestalt annimmt.

• Teilen Sie das Feature in Ebenen auf. Jede Ebene sollte eine einzelne, kohärente Änderung sein, die eigenständig überprüft werden kann.
  • Halten Sie jede Ebene klein genug, damit der Pull Request schnell zu lesen ist. Wenn für die Überprüfung einer Ebene eine lange Beschreibung nötig erscheint, ist sie wahrscheinlich zu groß.
  • Entscheiden Sie die Grenzen selbst, oder arbeiten Sie mit Copilot an einem Plan zusammen. So oder so besitzen Sie die Form des Stack.
• Ordnen Sie die Schichten nach Abhängigkeit an. Grundlegende Änderungen gehören nach unten. Alles, was von ihnen abhängt, steigt ebenfalls. Für die Authentifizierung kann dies Folgendes sein:
  • Ebene 1: Datenmodell und Migration
  • Layer 2: CRUD-Endpunkte
  • Layer 3: JWT Middleware und Guards
  • Layer 4: Integrations- und Unit-Tests

Beispiel-Prompts

• Propose a layered approach to add user authentication to this app. Order the layers by dependency, keeping each layer independently reviewable.
• Review my planned layers and flag any that are too large or that depend on a branch above them.

2. Erstellen Sie zuerst die untere Ebene

Starten Sie den Stack mit der Foundation. Alles oben Genannte hängt davon ab, diese Ebene korrekt umzusetzen.

• Informiere Copilot, dass du einen gestapelten Pull Request erstellen wirst, und bitte es, die erste Ebene auf Grundlage deines Plans zu erstellen. Der Agent verwendet den gh-stack Skill, um die erste Verzweigung des Stapels zu erstellen.
• Wenn Sie den Stack selbst erstellen möchten, erstellen Sie ihn direkt mit gh stack init, unter Verwendung eines Präfixes, um Verzweigungsnamen übersichtlich zu halten, zum Beispiel gh stack init BRANCH-NAME-1.
• Überprüfen Sie die generierte Änderung selbst, bevor Sie fortfahren. Ein Fehler in der untersten Schicht verteilt sich auf jede Verzweigung darüber, also überprüfen Sie sie, bevor Sie fortfahren.

Beispiel-Prompts

• Start the pr-stack and build only the first layer: the user data model and migration.
• Conduct a review of the generated code and confirm this branch contains only the data model and migration, and nothing that belongs in a later layer.

3. Stapeln Sie jede neue Codeebene aufeinander

Wenn die Grundlage eingerichtet ist, erstellen Sie den Rest des Features eine Ebene nach der anderen.

• Fordern Sie Copilot auf, die nächste Ebene hinzuzufügen und sie im Kontext der darunterliegenden Ebenen zu implementieren. Der Agent fügt oben im Stapel einen Branch hinzu und committet die Arbeit dort.
• Wenn Sie einen Branch selbst hinzufügen möchten, verwenden Sie gh stack add BRANCH-NAME-NEXT.
• Wenn eine Ebene zu groß wird, überlegen Sie, ob sie von ihrem vorgesehenen Zweck abgewichen ist oder ob Sie tatsächlich zwei Ebenen anstelle einer benötigen.
• Erstellen Sie neue Branches für jede Schicht, sodass jeder Branch ein sauberes, eigenständiges Diff bleibt.
• Wenn Sie bereit sind, Pull Requests zu erstellen, bitten Sie Copilot, Ihren Stack einzureichen, oder wenn Sie dies selbst tun möchten, verwenden Sie gh stack submit.
• Jeder Pull Request sollte für sich allein verständlich sein. Ein fokussierter Titel und eine präzise, aussagekräftige Beschreibung des Layers reicht in der Regel aus.

Beispiel-Prompts

• Add the next layer in a new branch on top: the CRUD endpoints that use the user model from the branch below.
• This branch is getting large. Suggest how it could be split into two independently reviewable layers.

4. Überprüfen Sie die Pull Requests selbst, bevor Sie eine Überprüfung beantragen

Jede Ebene ist klein und erleichtert auch die Selbstüberprüfung. Prüfen Sie jeden Branch, bevor Sie Teamkollegen einbeziehen. Reviewer sollten Änderungen erhalten, denen Sie bereits vertrauen.

• Führen Sie Ihre Tests, Linters und Codeüberprüfungen für jeden Branch aus. Lassen Sie Copilot Ihnen helfen, jede Ebene anhand Ihrer Standards zu überprüfen, bevor Sie Reviews anfordern.
• Informationen zu den Techniken zum gründlichen Überprüfen von KI-generierten Änderungen finden Sie unter Überprüfen von KI-generierten Code.

5. Fordern Sie Reviews für den Stack an, beginnend am unteren Rand

Mit den erstellten Ebenen erhalten Prüfer kleine Diffs anstelle eines großen Codeblocks.

• Wenn die Abhängigkeiten stark integriert sind, fordern Sie Reviews an, die unten im Stack beginnen, damit Sie Änderungen den Stack hinauf vor nachfolgenden Reviews integrieren können.
• Wenn Sie Überprüfungen von unterschiedlichen Personen für verschiedene Ebenen benötigen, können Prüfer parallel arbeiten. Eine Person kann das Datenmodell überprüfen, während eine andere die Endpunkte überprüft, und keine von beiden muss sich durch das gesamte Feature arbeiten.

6. Feedback einarbeiten

Das Feedback wird einzelnen Ebenen und nicht dem gesamten Feature zugeordnet. Mithilfe von Stapeln können Sie die richtige Ebene an Ort und Stelle fixieren und die Änderung nach oben weitergeben.

• Bitten Sie Copilot, die Ebene zu überarbeiten, die ein Prüfer gekennzeichnet hat. Der Agent wechselt zum rechten Branch, nimmt die Änderung vor und committet sie dort. Anschließend werden die darüber liegenden Ebenen neu gebaset, sodass sie den Fix wieder aufnehmen.
• Belassen Sie jede Änderung in der zugehörigen Ebene. Eine Änderung, die im falschen Branch vorgenommen wurde, kann verwirren und weiter oben im Stack Fehler verursachen.
• Wenn Sie Korrekturen vornehmen, bitten Sie Copilot, die oben genannten Branches neu zu basieren und Änderungen weiterzuverbreiten.
• Wenn Sie den Stapel selbst durchlaufen möchten, navigieren Sie zwischen Verzweigungen mit gh stack down, gh stack up oder gh stack checkout BRANCH-NAME. Erstellen Sie dann einen Commit für Ihre Änderungen, und führen Sie gh stack rebase --upstack aus, um Änderungen im Stack nach oben zu übertragen.

Beispiel-Prompts

• A reviewer flagged that the auth service doesn't handle expired tokens. Fix that on BRANCH-NAME and test the changes.
• I've rebased the layers above onto this fix. Check that the branch with endpoints still works with the change and flag anything that needs updating.

7. Zusammenführen von der unteren Ebene

Ein Stapel wird in der Reihenfolge zusammengeführt, beginnend mit dem Layer, der auf Ihren Haupt-Branch zeigt. Führen Sie alle Ebenen auf einmal oder einzeln zusammen, und GitHub richtet die nächste Ebene automatisch neu auf main aus.

• Führen Sie die Elemente des Stapels nacheinander zusammen, beginnend von unten nach oben, oder von einer beliebigen Stelle im Stapel aus; dabei werden alle Verzweigungen unterhalb des Pull Requests, den Sie zusammenführen, von unten nach oben zusammengeführt.
• Jeder Layer-Diff bleibt im Verhältnis zu seinem übergeordneten Element genau gleich, nur die Basis ändert sich, wodurch es einfach ist, jeweils eine Ebene zusammenzuführen, ohne dass sich dies auf laufende Arbeit oder Rezensionen auswirkt.
• Verwenden Sie die automatische Zusammenführung oder eine Merge-Warteschlange, sodass jeder Branch zusammengeführt wird, sobald er genehmigt ist und seine Prüfungen bestanden hat. Sie müssen nicht gleichzeitig auf den gesamten Stapel warten.

Sobald die oberste Ebene zusammengeführt wird, ist das gesamte Feature integriert. Jeder Teil ließ sich als kleine, gezielte Änderung effektiver prüfen als in einem großen Pull Request.

Weiterführende Lektüre

• Überprüfen von KI-generierten Code
• Verwalten von gestapelten Pull Requests