Codeänderungen in Pull Requests stapeln

Erstellen Sie einen Stapel kleiner, abhängiger Pull Requests, die schnell überprüft werden können.

In diesem Artikel

Große Pull Requests sind schwierig zu überprüfen und führen zu Engpässen, insbesondere wenn Sie in kurzer Zeit ein hohes Codevolumen generieren. Die Qualität der Überprüfung verschlechtert sich auch, wenn die Größe des Pull Request zunimmt. Prüfer können das Ergebnis überfliegen, Probleme übersehen oder die Bearbeitung des Pull Requests aufschieben, bis er veraltet und es zu Merge-Konflikten kommt.

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 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 die gh stack Erweiterung in GitHub CLI.

Voraussetzungen

Um diesem Tutorial zu folgen, müssen Sie GitHub CLI und die gh stack Erweiterung installieren. Sie benötigen Folgendes:

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

Installieren Sie in GitHub CLI die gh stack-Erweiterung.

gh extension install github/gh-stack

1. Entwerfen Sie einen Stack, bevor Sie Code generieren

Ein guter Stack ist wie das Bauen eines Hauses: Beginnen Sie mit einer starken Grundlage, rahmen Sie die Wände, installieren Sie die Verkabelung und bringen Sie dann den Trockenbau zu Ende. Jede Ebene basiert auf der darunter stehenden Ebene. Am Ende sollte ein Prüfer in der Lage sein, die Pull Requests von unten nach oben zu lesen und der Entwicklung des Features zu folgen.

  • 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 überblicken ist. Wenn für die Überprüfung einer Ebene offenbar eine lange Beschreibung nötig ist, ist sie wahrscheinlich zu groß.
    • Legen Sie die Grenzen selbst fest. Sie bestimmen die Form des Stack.
  • Ordnen Sie die Ebenen nach Abhängigkeit an. Grundlegende Änderungen gehören nach unten. Alles, was von ihnen abhängt, steigt ebenfalls. Für die Authentifizierung kann Folgendes verwendet werden:
    • Ebene 1: Datenmodell und Migration
    • Layer 2: CRUD-Endpunkte
    • Layer 3: JWT Middleware und Guards
    • Layer 4: Integrations- und Unit-Tests

2. Erstellen Sie zuerst die untere Ebene

Starten Sie den Stack mit der Foundation. Alles bisher Genannte hängt davon ab, dass diese Ebene richtig ist.

  • Erstellen Sie den Stack, und erstellen Sie die erste Ebene basierend auf Ihrem Plan. Erstellen Sie es mit gh stack init BRANCH-NAME-1, erwägen Sie die Verwendung eines Präfixes, um Verzweigungsnamen übersichtlich zu halten.
  • Überprüfen Sie die Änderung selbst, bevor Sie fortfahren. Ein Fehler in der unteren Ebene wirkt sich auf alle darüberliegenden Zweige aus, also überprüfen Sie sie, bevor Sie fortfahren.

3. Stapeln Sie jede neue Codeebene aufeinander

Wenn die Grundlage eingerichtet ist, erstellen Sie den Rest des Features Schicht für Schicht.

  • Fügen Sie die nächste Ebene hinzu, und implementieren Sie sie im Kontext der darunterliegenden Ebenen. Fügen Sie oben im Stapel einen Branch mit gh stack add BRANCH-NAME-NEXT hinzu und committen Sie die Arbeit dort.
  • Wenn eine Ebene zu groß wird, überlegen Sie, ob sie von ihrem Plan abgewichen ist oder ob Sie tatsächlich zwei Ebenen anstelle einer Ebene 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, übermitteln Sie Ihren Stack mit gh stack submit.
  • Lassen Sie jeden Pull Request eigenständig stehen. Ein fokussierter Titel und eine präzise, aussagekräftige Beschreibung des Layers reicht in der Regel aus.

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

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

  • Führen Sie Ihre Tests, Linters und Codescans auf jedem Branch aus, um jede Ebene anhand Ihrer Standards zu überprüfen, bevor Sie Reviews anfordern.

5. Fordern Sie Reviews für den Stapel an, von unten beginnend

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

  • Wenn die Abhängigkeiten stark integriert sind, bitten Sie um Reviews, die unten im Stack beginnen, damit Sie Änderungen im Stack vor nachfolgenden Überprüfungen integrieren können.
  • Wenn Sie Überprüfungen von verschiedenen Personen für verschiedene Ebenen benötigen, können Reviewer parallel arbeiten. Eine Person kann das Datenmodell überprüfen, während eine andere die Endpunkte überprüft, und keine von beiden muss sich durch die Prüfung des gesamten Features durcharbeiten.

6. Feedback einarbeiten

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

  • Überarbeiten Sie den Layer, den ein Prüfer gekennzeichnet hat. Wechseln Sie zum rechten Branch, nehmen Sie die Änderung vor und committen Sie sie dort.
  • Behalten Sie jede Korrektur auf der Ebene bei, zu der sie gehört. Eine Änderung, die im falschen Branch vorgenommen wurde, kann verwirren und weiter oben in der Kette Fehler verursachen.
  • Navigieren in Branches mit gh stack down, gh stack up oder gh stack checkout BRANCH-NAME. Führen Sie dann einen Commit für Ihre Änderungen aus, führen Sie gh stack rebase --upstack aus, um die obenstehenden Branches neu zu basen, und führen Sie dann gh stack push aus, um Änderungen im Stack nach oben zu übernehmen.

7. Zusammenführen von der unteren Ebene

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

  • Führen Sie die Elemente des Stapels nacheinander zusammen, wobei Sie von unten nach oben vorgehen, oder beginnen Sie an einer beliebigen Stelle im Stapel; alle Branches unterhalb des Pull Requests, den Sie zusammenführen, werden dann 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, einen Layer gleichzeitig zusammenzuführen, ohne dass sich dies auf laufende Arbeit oder Rezensionen auswirkt.
  • Verwenden Sie eine Merge-Warteschlange, sodass jeder Layer nach der Genehmigung und wenn ihre Prüfungen erfolgreich sind in der Reihenfolge zusammengeführt wird. Sie müssen nicht gleichzeitig auf den gesamten Stapel warten.

Sobald der oberste Layer zusammengeführt ist, ist das gesamte Feature verfügbar. Jede Änderung wurde effektiver eher als kleine, absichtliche Änderung denn als ein großer Pull Request überprüft.

Weiterführende Lektüre