Wie werde ich Patch-Guru?¶

Wenn Sie an der Implementierung eines neuen Features arbeiten oder Dokumentation zu einem bereits bestehenden hinzufügen, ist es leicht, sich von der Arbeit selbst mitreißen zu lassen und die ungeschriebenen Regeln für die Erstellung Ihrer Änderungen zu vergessen.

In diesem Abschnitt erfahren Sie, wie Sie Patches erstellen, die von Personen überprüft werden sollen.

Wenn Sie mit Ihrer Cloud ein externes Speicher-Plugin oder ein gemeinsam genutztes Dateisystem verwenden, können Sie testen, ob es funktioniert, indem Sie eine zweite Freigabe oder einen zweiten Endpunkt erstellen. So können Sie das System testen, bevor Sie die neue Version Ihrem Speicher anvertrauen.

Wissen, wie man einen Patch strukturiert, die die Wartung während des gesamten Review-Prozesses erleichtert.
Wissen, wie man einen Patch strukturiert, der für Community-Mitglieder einfacher zu überprüfen ist.

Die richtige Größe¶

Die Überprüfung großer Patches ist sehr unangenehm und zeitaufwendig, daher empfehlen wir immer, Ihre Änderungen in kleinere Blöcke aufzuteilen.

Während es keine magische Zahl gibt, versuche die Größe Ihrer Änderungen so klein wie möglich zu halten, aber unter ein paar hundert Zeilen wurden insgesamt geändert. Patches, die mit wenig Code-Änderungen teststark sind, erfordern genauso viel Aufwand wie codestarke Änderungen.

In seltenen Fällen, in denen es für eine Änderung keine gute logische Aufteilung gibt und Ihr Patch auf tausend Zeilen oder mehr wachsen kann. In einigen Fällen ist es akzeptabel, da Sie die zugehörigen Teständerungen nicht in einen anderen Patch extrahieren können, aber es wird nicht dringend empfohlen.

Versuchen Sie immer, so viel wie möglich in andere Patches zu extrahieren, wie z.B. Dokumentation oder logische Teile der Funktionalität, die nicht von gemeinsamen Funktionen in einer unteren Schicht abhängig sind.

Längere Patches benötigen mehr Zeit zum Überprüfen; wo immer Sie können, halten Sie die Länge angemessen. Und wo Sie es nicht können, können Sie den Reviewern helfen, indem Sie Codekommentare hinzufügen und eine detaillierte Commit-Meldung schreiben, um die Änderungen zu beschreiben, die Sie in Ihrem Patch vorgenommen haben.

Patchketten, Depends-On-Tag und Gerrit-Topics¶

Im Falle komplexer Feature-Implementierungsarbeiten, wenn Sie Änderungen an mehreren Modulen desselben Projekts oder an mehreren Projekten vornehmen müssen, müssen Sie sehr sorgfältig mit der Verwaltung der Abhängigkeiten umgehen.

Abhängig von der Struktur Ihres Designs stehen Ihnen mehrere Optionen zur Verfügung. Sie können die Änderungen entweder in Patchketten organisieren oder das Tag’Depends-On‘ verwenden.

Depends-On Tag¶

Wenn Sie Änderungen in mehreren Projekt-Repositories haben, können Sie abhängige Patches mit dem Tag’Depends-On‘ markieren. Der Tag wird als Link in der Commit-Nachricht angezeigt, der Ihnen und auch den Reviewern hilft, zwischen den Abhängigkeiten Ihrer Änderungen zu verfolgen und zu navigieren.

Das ‚Depends-On‘ Tag ist ein Marker für Ihre Änderungen und bei Verwendung kann ein Patch erst dann zusammengeführt werden, wenn alle seine Abhängigkeiten gelandet sind.

Das Tag kann auch auf Patches angewendet werden, die für das gleiche Repository vorgeschlagen werden. In diesem Fall sind die Änderungen getrennt genug, um unabhängig voneinander gehalten zu werden, was bedeutet, dass Sie, wenn Sie Änderungen durch Review-Kommentare korrigieren müssen, dies auf Patch-Basis tun können. Dies gilt auch für die Umbasierung jedes Patches.

Bemerkung

Wenn Sie den Tag „Depends-On“ verwenden, müssen Sie alle Änderungen für eine Feature-Implementierung oder Dokumentationsänderung herunterladen, um das Feature zu testen oder die Dokumentation mit allen vorgenommenen Änderungen zu erstellen. Git wird sich in diesem Fall nicht um die automatische Behandlung der Abhängigkeiten kümmern.

Patchketten¶

In einigen Fällen, wenn Sie die erforderlichen Änderungen in kleinere Blöcke aufteilen, können Sie es nicht vermeiden, direkte Abhängigkeiten zwischen ihnen zu haben, die verhindern, dass Sie unabhängige Änderungen vornehmen. Sie müssen Ihre Änderungen in einer Kette organisieren, um die Abhängigkeiten zu pflegen, die eine zusätzliche Sorgfalt erfordern, wenn Sie mit diesen Änderungen arbeiten.

Selbst wenn Sie eine Kette von Patches haben, müssen Sie Code-Änderungen und zugehörige Tests in einem Patch aufbewahren, da Sie nicht garantieren können, dass beide rechtzeitig für eine Veröffentlichung landen.

Wenn Sie eine Kette haben, hilft Ihnen Gerrit, indem es alle Commit-Titel in der Spalte’Related Changes‘ in der rechten oberen Ecke der Gerrit-Benutzeroberfläche auflistet. Die Titel sind auch Links, die Ihnen helfen, zwischen den Änderungen zu navigieren, um sie beim Hochladen einer neuen Version zu überprüfen.

Wie geht man mit Ketten um?¶

Eine Patchkette ist einfach zu handhaben, wenn man ein paar Empfehlungen beachtet:

Haben Sie immer einen lokalen Zweig für diese Änderungen, um sicherzustellen, dass Sie sie nicht mit Änderungen im Zusammenhang mit einem anderen Feature oder einer Fehlerbehebung vermischen.
Behandeln Sie eine Kette immer als einen Block von Änderungen, indem Sie die gesamte Kette neu aufbauen und sie auf dem neuesten Stand halten, wenn Sie einen Patch ändern, um Kommentare zur Überprüfung zu korrigieren oder Änderungen hinzuzufügen.
Um einen Patch innerhalb einer Kette zu ändern, müssen Sie eine interaktive Datenbank verwenden:

git rebase -i HEAD^

You need as many ‚^‘ as the number of the patch you want to edit first from the top of the chain. Alternatively you may wish to use git-restack, which figures out the appropriate git rebase command for you.

Gerrit also provides you options to edit the patch itself or only the commit message and a few more for more advanced changes, like modifying the author.

Um die gesamte Kette herunterzuladen, müssen Sie den Top-Patch herunterladen und Git lädt automatisch alle abhängigen Patches in der Kette herunter.
Wenn Sie nur den oberen Patch in der Kette ändern müssen, kann dies auf die gleiche Weise geschehen, wie Sie einzelne Patches aktualisieren.
Wenn Sie Änderungen in einer Kette hochladen, werden nur die Patches hochgeladen, die aktualisiert wurden. Dies bedeutet auch, dass die Bewertungspunkte bei niedrigeren Werten in der Kette unberührt bleiben.
Überprüfen Sie immer die Änderungen, die Sie an jedem Patch vorgenommen haben, und achten Sie darauf, dass Sie die Änderungen im richtigen Patch vorgenommen haben, da Patches immer noch einzeln zusammengeführt werden und es keine Garantie dafür gibt, dass die gesamte Kette gleichzeitig gelandet wird.

For a more in-depth look at managing patch chains, see Tutorial: Developing Changes In A Series.

Gerrit Topics¶

Sie haben die Möglichkeit, ein Thema für Ihre Änderungen anzugeben, wenn Sie sie zur Überprüfung hochladen. Während Gerrit-Topics keine Abhängigkeit zu Ihren Patches hinzufügen, können Sie eine Suche basierend auf dem Thema anwenden, die Ihnen alle relevanten Änderungen in allen Projekten anzeigt, in denen es Patches mit dem gleichen Thema gibt. Gerrit wird sie Ihnen auch in der Spalte ‚Same Topic‘ oben rechts auf der Seite einer Rezension zeigen.

Dies ist eine gute Möglichkeit, um die Verfolgung von Änderungen zu erleichtern, z.B. bei der Implementierung von Funktionen, Bugfixes oder Dokumentationsarbeiten.

Wie strukturiert man seine Änderungen?¶

Wenn Ihr Workitem über eine bestimmte Größe hinausgeht und Sie mehrere Patches hochladen müssen, ist es wichtig, es sowohl bei Patchketten als auch bei unabhängigen Änderungen gut zu strukturieren.

Es ist eine gute Praxis, Änderungen nach Modulen in einem Projekt zu gruppieren, z.B. virtuelle Treiberänderungen, Compute Manager und API-Änderungen im Falle von OpenStack Compute.

Durch die Gruppierung der Änderungen pro Modul können Sie auch die Kette oder Abhängigkeiten durch die Hierarchie der Komponenten konstruieren und die API-Änderungen immer aufrechterhalten, da dies die neue Funktionalität ermöglicht und diese Änderung von allem abhängt, was Sie sonst noch für Ihr Design benötigen.

Darüber hinaus können Sie auch in die Funktionalität schauen, um kleinere Bausteine zu finden und Ihre Änderungen kleiner zu machen. Beispielsweise können Änderungen an einem Objekt zuerst implementiert werden, die Sie später bei der Implementierung neuer API-Funktionen verwenden werden.

Structural split of Changes¶

The cardinal rule for creating good commits is to ensure there is only one „logical change“ per commit. There are many reasons why this is an important rule:

The smaller the amount of code being changed, the quicker and easier it is to review and identify potential flaws.
If a change is found to be flawed later, it may be necessary to revert the broken commit. This is much easier to do if there are not other unrelated code changes entangled with the original commit.
When troubleshooting problems using Git’s bisect capability, small well defined changes will aid in isolating exactly where the code problem was introduced.
When browsing history using git annotate or git blame, small well defined changes also aid in isolating exactly where and why a piece of code came from.

Der richtige Inhalt¶

Änderungen, die nichts mit einer Funktionsimplementierung oder einem Fehlerbericht zu tun haben, können hochgeladen werden, werden aber von den Prüfern weniger begrüßt.

Die Verbesserung des Codes oder der Dokumentation sollte Teil eines größeren Aufwandes sein, wie z.B. wenn Sie Tippfehler in der Dokumentation beheben möchten, dann sollten Sie es für einen größeren Block tun, wie einen ganzen Leitfaden. Es wird auch vorgezogen, eine Story mit Aufgaben für ein solches Workitem zu melden, die später verfolgt werden kann.

Ähnlich verhält es sich bei Code-Verbesserungen. Da die Community groß und weltweit ist, haben wir Programmierrichtlinien, aber der Stil jedes Einzelnen kann immer noch sehr unterschiedlich sein. Wir erzwingen keinen bestimmten Codierstil, daher sind Änderungen im Zusammenhang mit der Behebung weniger willkommen und Quellen für sehr dogmatische Argumente, die vermieden werden sollten.

Im Falle von Code Refactoring-Arbeiten, die den Code durch Umstrukturierung und Löschen unbenutzter Codeausschnitte lesbarer und einfacher zu pflegen machen, wird dringend empfohlen, sich mit dem Projektteam abzustimmen und zunächst eine Story in StoryBoard zu berichten und dann die relevanten Änderungen zur Überprüfung an Gerrit hochzuladen.

Wie werde ich Patch-Guru?