Die Magie von Pull Requests

1. Vom Zusammenfuehren zum Vorschlag: Wozu braucht man Pull Requests?

In der letzten Vorlesung haben wir gelernt, Zweige (merge) auf unserem lokalen Computer zusammenzufuehren. Das funktioniert hervorragend, wenn Sie allein arbeiten. Aber was ist, wenn ein ganzes Team an einem Projekt arbeitet? Wenn jeder seine Aenderungen direkt in den Hauptzweig main zusammenfuehrt, beginnt bald das Chaos: Jemand koennte versehentlich fehlerhaften Code einfuegen, den Build zerstoeren oder einen wichtigen Teil der Arbeit eines Kollegen loeschen.

Um das zu vermeiden, wird in der Teamarbeit ein anderer Ansatz verwendet. Statt Aenderungen sofort zusammenzufuehren, erstellen Sie einen Zusammenfuehrungsvorschlag. Dieser Vorschlag nennt sich Pull Request (abgekuerzt PR) oder auf manchen Plattformen Merge Request.

Pull Request ist eine offizielle Bitte: "Bitte holt (pull) meine Aenderungen aus meinem Zweig und fuegt (merge) sie in den Hauptzweig ein". Aber es ist nicht nur eine Bitte, sondern eine ganze Flaeche fuer Diskussion, Pruefung und Verbesserung des Codes, bevor er in main landet.

2. Der Standard-Workflow mit Pull Request

Lassen Sie uns Schritt fuer Schritt ansehen, wie ein typischer Workflow bei der Erstellung neuer Funktionalitaet aussieht.

Bevor Sie einen Zweig fuer eine neue Aufgabe erstellen, stellen Sie sicher, dass Sie alle fertigen Commits per push gesendet und den Hauptzweig main mit Update Project aktualisiert haben.

Andernfalls gelangen all Ihre "vergessenen" lokalen Commits aus main versehentlich in den neuen Pull Request und sorgen fuer Verwirrung bei Ihren Kollegen.

Schritt 1. Erstellen Sie einen Zweig fuer die neue Aufgabe.

Wie bisher beginnt jede neue Arbeit mit dem Erstellen eines separaten Zweigs. Angenommen, wir moechten unserem Projekt eine Datei mit Regeln fuer Beitragende hinzufuegen. Erstellen wir den Zweig feature/add-contribution-guide.

Schritt 2. Nehmen Sie Aenderungen vor und senden Sie Ihren Zweig an GitHub.

Erstellen Sie im neuen Zweig die Datei CONTRIBUTING.md (nach dem Erstellen auf Add klicken) und schreiben Sie eine Nachricht an andere Entwickler hinein. Danach fuehren Sie Commit and Push mit einer klaren Nachricht aus, zum Beispiel: docs: Add contribution guide.

Das ist ein entscheidender Schritt! Ein Pull Request wird auf Grundlage eines Zweigs erstellt, der bereits auf dem entfernten Server existiert. Deshalb muessen Sie, bevor Sie einen PR erstellen, Ihren neuen Zweig unbedingt zu GitHub senden (push).

3. Pull Request in IntelliJ IDEA erstellen

Jetzt, da Ihr Zweig auf GitHub existiert, koennen Sie einen Pull Request erstellen.

Schritt 1. Oeffnen Sie den Reiter Pull Requests.

Auf der linken Seitenleiste der IDE finden Sie den Reiter (Tool Window) Pull Requests. Oeffnen Sie ihn und klicken Sie auf das Symbol + (oder die Schaltflaeche Create Pull Request), um einen neuen PR zu erstellen.

Schritt 2. Fuellen Sie die Daten fuer den PR aus.

Die IDE oeffnet automatisch eine bequeme Oberflaeche fuer Sie. Ihre Aufgabe ist es, sie sinnvoll auszufuellen. Lassen Sie uns die wichtigsten Felder durchgehen:

1. Titel: Die IDE fuegt hier oft den Namen des Zweigs oder den Text Ihres letzten Commits ein. Stellen Sie sicher, dass der Titel knapp, klar und aussagekraeftig ist.
2. Beschreibung: Hier erklaeren Sie Ihren Kollegen im Detail, was Sie genau gemacht haben und warum.
3. Reviewer: Hier waehlen Sie einen oder mehrere Kollegen aus, die Ihren Code pruefen sollen. Im Lernprojekt ueberspringen wir diesen Schritt, aber in der realen Arbeit ist er erforderlich.
4. Assignees: Hier geben Sie normalerweise sich selbst an. Das bedeutet, dass Sie der Autor und die hauptverantwortliche Person fuer diese Aufgabe und fuer Aenderungen nach dem Review sind.

Nachdem alle Felder ausgefuellt sind, koennen Sie ruhig auf Create Pull Request klicken.

4. Code Review: Pruefung und Diskussion

Nach der Erstellung des PR beginnt die wichtigste Phase — das Code Review. Ihre Kollegen koennen Ihren PR oeffnen, alle Aenderungen ansehen und Kommentare hinterlassen.

Sie koennen alle Diskussionen direkt in der IDE im Reiter Pull Requests sehen. Wenn jemand einen Kommentar zu einer Codezeile hinterlaesst, erhalten Sie eine Benachrichtigung und koennen antworten, ohne in den Browser zu wechseln.

Was tun, wenn Sie gebeten werden, Aenderungen vorzunehmen?

Ganz einfach! Sie muessen keinen neuen PR erstellen. Nehmen Sie einfach die benoetigten Aenderungen im Code Ihres aktuellen Zweigs vor, erstellen Sie einen neuen Commit und senden Sie ihn. Der Pull Request auf GitHub wird automatisch aktualisiert und fuegt Ihre neuen Commits zur bestehenden Diskussion hinzu.

5. Abschluss der Arbeit: Zusammenfuehren und Loeschen des Zweigs

Wenn alle Anmerkungen korrigiert sind und das Team Ihre Aenderungen bestaetigt (Sie erhalten ein "Approve"), kann der Pull Request zusammengefuehrt werden. Normalerweise macht das ein Senior Developer oder Sie selbst, wenn Sie dafuer im Repository berechtigt sind.

Schritt 1. Merge

Das Zusammenfuehren erfolgt meist auf der GitHub-Website oder direkt aus dem Pull-Requests-Fenster in der IDE. Auf GitHub erscheint unter Ihrem PR eine grosse gruene Schaltflaeche Merge pull request. Nach dem Klicken wird Ihr Code Teil des Hauptzweigs main.

Schritt 2. Zweig loeschen.

Nach dem Zusammenfuehren wird Ihr `feature`-Zweig nicht mehr benoetigt und sollte geloescht werden, damit das Repository nicht unuebersichtlich wird. GitHub bietet Ihnen dies selbst an und zeigt die Schaltflaeche Delete branch.

Vergessen Sie auch nicht, die lokale Kopie des Zweigs in Ihrer IDE zu loeschen und auf dem Zweig main Update Project auszufuehren, um die Ergebnisse des Zusammenfuehrens auf Ihren Computer zu holen.

6. Drei Regeln fuer einen guten Commit

Ein guter Commit ist nicht nur eine gute Nachricht, sondern auch ein sinnvoller Inhalt. Damit Ihre Aenderungshistorie sauber, nuetzlich und professionell bleibt, sollten Sie drei einfache Regeln beachten.

Regel 1: Schreiben Sie klare Nachrichten nach dem Standard

Ihre Commits sind Nachrichten, die Sie an Ihr Team und an Ihr spaeteres Ich senden. Eine Historie voller Nachrichten wie "fix" oder "update" ist voellig nutzlos. Der populaerste Standard heisst Conventional Commits. Er schlaegt die folgende Struktur vor:

<type>: <short description>

Type ist ein kurzes Wort, das die Kategorie Ihrer Aenderungen beschreibt:

• feat: (feature) — fuer neue Funktionalitaet.
• fix: — fuer die Behebung eines Fehlers.
• docs: — fuer Aenderungen in der Dokumentation.
• style: — fuer Formatierungsanpassungen, die die Logik des Codes nicht beeinflussen.
• refactor: — fuer Aenderungen im Code, die keine neue Funktionalitaet hinzufuegen und keine Fehler beheben.
• test: — fuer das Hinzufuegen oder Korrigieren von Tests.
• chore: — fuer Routineaufgaben ohne direkten Bezug zum Code (Abhaengigkeiten aktualisieren, Build einrichten).

Beispiele:

• Schlecht: fixed bug
• Gut: fix: Correct user login validation

• Schlecht: readme
• Gut: docs: Update installation instructions

Regel 2: Ein Commit — eine logische Aenderung (Atomaritaet)

Versuchen Sie nicht, in einem Commit einen Bugfix, das Hinzufuegen einer neuen Funktion und ein Refactoring alten Codes unterzubringen. Einen solchen Commit im Review zu pruefen ist sehr schwer, und es ist fast unmoeglich, ihn schmerzlos zurueckzunehmen, wenn etwas schiefgeht.

Jeder Commit sollte nur eine konkrete Aufgabe loesen.

• Schlecht: ein Commit mit der Nachricht "Update user page", der ein Avatar-Feld hinzufuegt, einen Fehler in der Namensvalidierung behebt und die Button-Farben aendert.
• Gut: drei verschiedene Commits:
  1. feat: Add avatar upload to user profile
  2. fix: Correct username validation logic
  3. style: Update button colors on user page

Wenn Sie bemerkt haben, dass Sie im Eifer des Gefechts zu viel in einer Datei geaendert haben, erlaubt Ihnen IntelliJ IDEA, nicht gleich die ganze Datei zu committen! Im Commit-Fenster koennen Sie die Datei aufklappen und nur die Haeckchen bei den Code-Fragmenten (chunks) setzen, die zu einer bestimmten logischen Aufgabe gehoeren.

Regel 3: Ein Commit darf das Projekt nicht zerstoeren

Jeder Commit im Hauptzweig sollte das Projekt in einem lauffaehigen Zustand hinterlassen. Vor dem Erstellen muessen Sie mindestens sicherstellen, dass der Code kompiliert wird, zum Beispiel indem Sie go build ausfuehren. Aber wie stellen Sie sicher, dass Sie nicht versehentlich etwas in einem anderen Teil des Systems zerstoert haben? Sich nur auf manuelle Pruefung zu verlassen, ist riskant.

Hier hilft Automatisierung. In diesem Kurs werden wir keine automatischen Prozesse einrichten, aber Sie sollten wissen, wie das in echten Projekten funktioniert. Moderne Teams verwenden Systeme der Continuous Integration (CI), etwa GitHub Actions.

Wie funktioniert das?

Sie schreiben den Code und die Tests dafuer. Danach richten Sie oder DevOps direkt auf GitHub ein spezielles Szenario (Workflow) ein. Sobald Sie nun einen push in Ihren Pull Request senden, geschieht die Magie:

1. GitHub Actions erkennt dieses Ereignis und startet Ihr Szenario auf dem entfernten Server.
2. Es "baut" das Projekt automatisch und fuehrt alle von Ihnen geschriebenen Tests aus (zum Beispiel durch Ausfuehren des Befehls go test).
3. Wenn alle Tests erfolgreich bestanden werden, erscheint neben Ihrem Commit auf GitHub ein gruenes Haeckchen. Das ist ein Signal fuer das ganze Team, dass Ihre Aenderungen sicher sind.
4. Wenn auch nur ein Test fehlschlaegt, sehen Sie ein rotes Kreuz. Einen solchen PR in den Hauptzweig zusammenzufuehren ist bis zur Behebung der Fehler streng verboten.

            graph LR
            subgraph GitHub
            A[Developer] -- "push" --> B(Repository)
            B -- "Event: push" --> C{GitHub Actions}
            end

            subgraph Workflow
            C -- "Start" --> D[Test run]
            D --> E[Successful]
            D --> F[Unsuccessful]
            end

            subgraph Notifications
            F --> G((Email))
            G --> H[Developer]
            G --> I[Team]
            end

            style F fill:#f99,stroke:#333,stroke-width:2px
            style G fill:#ccf,stroke:#333,stroke-width:2px
        

Benachrichtigungen koennen eingerichtet werden. Wenn Tests fehlschlagen, kann GitHub Actions Ihnen oder dem ganzen Team eine E-Mail senden. Ein solcher Ansatz schafft eine Kultur, in der Tests nicht nur Formalitaet sind, sondern ein unverzichtbarer Teil der Entwicklung, und jeder die Verantwortung fuer die Qualitaet seines Codes traegt.