6.2 GitHub - Mitwirken an einem Projekt

Tony ist auf der Suche nach Code, der auf seinem programmierbaren Arduino-Mikrocontroller läuft und hat auf GitHub unter https://github.com/schacon/blink eine tolle Programmdatei gefunden.

Das einzige Problem ist, dass die Blinkfrequenz zu schnell ist. Wir finden es viel angenehmer, 3 Sekunden statt 1 Sekunde zwischen den einzelnen Zustandsänderungen zu warten. Lass uns also das Programm verbessern und es als Änderungsvorschlag an das Projekt senden.

Zuerst klicken wir, wie bereits erwähnt, auf die Schaltfläche 'Fork', um unsere eigene Kopie des Projekts zu erhalten. Unser Benutzername hier ist „tonychacon“, also ist unsere Kopie dieses Projekts unter https://github.com/tonychacon/blink zu finden und dort könnten wir es bearbeiten. Wir werden es aber lokal klonen, einen Feature-Branch erstellen, den Code ändern und schließlich diese Änderung wieder auf GitHub pushen.

Wenn wir nun zu unserem Fork auf GitHub zurückkehren, können wir sehen, dass GitHub bemerkt hat, dass wir einen neuen Feature-Branch gepusht haben. GitHub zeigt uns einen großen grünen Button, um unsere Änderungen zu überprüfen und einen Pull Request zum ursprünglichen Projekt zu öffnen.

Du kannst alternativ auch die Seite „Branches“ bei https://github.com/<user>/<project>/branches aufzurufen, um deinen Branch auszuwählen und von dort aus einen neuen Pull Request zu öffnen.

Wenn wir auf die grüne Schaltfläche klicken, sehen wir einen Bildschirm, auf dem du aufgefordert wirst, deinen Pull Request einen Titel und eine Beschreibung zu geben. Es ist fast immer sinnvoll, sich hierfür ein bisschen Mühe zu geben. Eine gute Beschreibung hilft dem Eigentümer des ursprünglichen Projekts, festzustellen, warum du die Änderungen machst, ob deine vorgeschlagenen Änderungen korrekt sind und ob die Annahme der Änderungen das ursprüngliche Projekt verbessern würden.

Wir erhalten auch eine Liste der Commits in unserem Feature-Branch, die dem master Branch „voraus“ (engl. ahead) sind (in diesem Fall nur der eine) und ein vereinheitlichtes Diff aller Änderungen, die vorgenommen werden, falls dieser Branch vom Projektleiter gemerged wird.

Wenn du in diesem Fenster auf die Schaltfläche 'Create pull request' klickst, wird der Eigentümer/Leiter des Projekts, für das du eine Abspaltung (engl. Fork) vorgenommen hast, benachrichtigt. Er wird informiert, dass jemand eine Änderung vorschlägt, und verlinkt auf eine Seite, die alle diese Informationen enthält.

An dieser Stelle kann sich der Projektverantwortliche die vorgeschlagene Änderung ansehen und mergen, ablehnen oder kommentieren. Nehmen wir an, er mag die Idee, würde aber eine etwas längere Zeit bevorzugen, in der das Licht aus ist.

Während diese Unterhaltung über E-Mail in den in Kapitel5 Verteiltes Git dargestellten Workflows stattfinden kann, geschieht dies bei GitHub online. Der Projektverantwortliche kann das vereinheitlichte Diff überprüfen und einen Kommentar hinterlassen, indem er auf eine der Zeilen klickt.

Sobald der Betreuer diesen Kommentar abgibt, erhält die Person, die den Pull-Request geöffnet hat (und auch alle anderen, die das Repository beobachten), eine Benachrichtigung. Wir werden das später noch einmal anpassen, aber wenn er E-Mail-Benachrichtigungen eingeschaltet hat, bekommt Tony eine E-Mail wie diese:

Jeder kann auch allgemeine Kommentare zum Pull Request hinterlassen. Auf der Pull Request Diskussions-Seite sehen wir ein Beispiel dafür, wie der Projektleiter sowohl eine Zeile Code kommentiert als auch einen allgemeinen Kommentar im Diskussionsbereich hinterlässt. Du siehst, dass auch die Code-Kommentare in das Diskussionsfenster sichtbar sind.

Jetzt kann der Beitragende sehen, was er tun muss, damit seine Änderung akzeptiert wird. Zum Glück ist das sehr einfach. Wo du über E-Mail deine Daten erneut in die Mailingliste eintragen musst, committest du mit GitHub einfach erneut in den Feature-Branch und pushst, wodurch der Pull-Request automatisch aktualisiert wird. Im finalen Pull-Request siehst du auch, dass der alte Code-Kommentar in dem aktualisierten Pull-Request zusammengeklappt wurde, da er auf eine inzwischen geänderte Zeile basiert.

Das Hinzufügen von Commits zu einem bestehenden Pull Request löst keine weitere Benachrichtigung aus. Nachdem Tony seine Korrekturen gepusht hat, beschließt er, einen Kommentar zu hinterlassen, um den Projektträger darüber zu informieren, dass er die gewünschte Änderung vorgenommen hat.

Eine bemerkenswerte Besonderheit ist, dass du den „vereinheitlichten“ Diff erhältst, wenn du auf die Registerkarte „Files Changed“ in diesem Pull-Request klickst – d.h. die gesamte aggregierte Differenz, die in deinen Hauptbranch eingebracht würde, wenn dieser Feature-Branch gemerged würde. Im Sinne von git diff zeigt es dir grundsätzlich automatisch git diff master…<branch> für den Branch, auf dem dieser Pull Request basiert. Siehe Kapitel 5 Festlegen, was eingebracht wird für weitere Informationen über diese Art von Diffs.

Außerdem prüft GitHub, ob der Pull-Request sauber mergen würde und stellt eine Schaltfläche zur Verfügung, mit der du den Merge auf dem Server durchführen könntest. Diese Schaltfläche erscheint nur, wenn du Schreibzugriff auf das Repository hast und ein trivialer Merge möglich ist. Wenn du darauf klickst, führt GitHub einen „non-fast-forward“-Merge durch, was bedeutet, dass selbst wenn es sich bei dem Merge um einen schnellen Vorlauf (engl. fast-forward) handeln könnte, immer noch ein Merge-Commit erstellt wird.

Wenn du möchtest, kannst du den Branch einfach herunterladen (engl. pull) und lokal zusammenführen (engl. merge). Wenn du diesen Branch mit dem master Branch mergst und ihn nach GitHub pushen willst, wird der Pull Request automatisch geschlossen.

Das ist der grundsätzliche Workflow, den die meisten GitHub-Projekte verwenden. Feature-Branches werden erstellt, Pull-Requests werden geöffnet, es folgt eine Diskussion, möglicherweise wird eine weitere Überarbeitung des Branches durchgeführt und schließlich wird der Request entweder geschlossen oder zusammengeführt.

Es ist wichtig zu verstehen, dass viele Projekte Pull-Requests nicht wirklich als eine Reihe perfekter Patches betrachten, die sauber angewendet werden sollten, so wie es bei den meisten Mailinglisten-basierten Projekte mit Patch-Serienbeiträge ist. Die meisten GitHub-Projekte betrachten Pull-Request-Branches als iterative Dialoge für vorgesehen Änderungen. Dies führt in der Regel zu einem vereinheitlichten Diff, der am Ende gemerged wird.

Das ist ein wichtiger Unterschied, denn im Allgemeinen wird die Änderung vorgeschlagen, bevor der Code fertig ist, was bei Beiträgen von Patch-Serien auf Mailinglistenbasis weitaus seltener ist. So kann früher mit den Projekt-Betreuern gesprochen werden und somit ist die richtige Lösung eher eine Art Gemeinschaftsarbeit. Wenn Code mit einem Pull-Request vorgeschlagen wird und die Maintainer oder die Community eine Änderung vorschlagen, wird die Patch-Serie im Allgemeinen nicht neu aufgerollt. Es wird der Unterschied als neuer Commit an den Branch weitergegeben (gepusht), wodurch der Dialog an dieser Stelle im intakten Kontext der vorherigen Arbeit fortgesetzt wird.

Wenn du beispielsweise zurückgehen und dir den finalen Pull-Request erneut ansehen willst, wirst du feststellen, dass der Beitragende seinen Commit nicht rebased und einen weiteren Pull-Request geöffnet hat. Stattdessen wurden neue Commits hinzugefügt und sie in den bestehenden Branch gepusht. Wenn du dir also zu einen späterem Zeitpunkt den Pull Request nochmal anschaust, kannst du den gesamten Kontext finden, in dem die Entscheidungen getroffen wurden. Wenn du auf der Website auf die Schaltfläche „Merge“ klickst, wird ein Merge-Commit erstellt, der auf den Pull-Request verweist. Somit kannst du bei Bedarf sehr schnell die ursprüngliche Diskussion begutachten.

Wenn dein Pull-Request veraltet ist oder anderweitig nicht sauber zusammengeführt wird, solltest du ihn reparieren, damit der Betreuer ihn leicht mergen kann. GitHub wird das für dich testen und dich am Ende jedes Pull Requests darüber informieren, ob das Merge trivial ist oder nicht.

Wenn du etwa „Pull Request lässt sich nicht sauber mergen“ siehst, solltest du deinen Branch so reparieren, dass er grün wird und der Maintainer keine zusätzliche Arbeit leisten muss.

Du hast grundsätzlich zwei Möglichkeiten, wie du das realisieren kannst. Du kannst deinen Branch entweder auf den Ziel-Branch rebasen (normalerweise den master Branch des von dir geforkten Repositorys), oder du kannst den Ziel-Branch mit deinem Branch mergen.

Die meisten Entwickler auf GitHub werden sich aus den gleichen Gründen für Letzteres entscheiden, die wir im vorherigen Abschnitt erläutert haben. Was wichtig ist, ist die Verlaufskontrolle und der endgültige Merge, so dass das Rebasing nicht viel mehr bringt als eine etwas aufgeräumtere Historie. Im Gegenzug ist es viel schwieriger und fehleranfälliger.

Wenn du im Ziel-Branch mergen willst, um deinen Pull-Request zusammenzuführen zu können, solltest du das ursprüngliche Repository als neuen Remote hinzufügen. Dann machst du ein git fetch darauf, führst den Haupt-Branch dieses Repositorys in deinem Feature-Branch zusammen, behebst alle Probleme und pushst es schließlich wieder in den gleichen Branch, in dem du den Pull-Request geöffnet hast.

Nehmen wir zum Beispiel an, dass der ursprüngliche Autor in dem von uns zuvor verwendeten Beispiel „tonychacon“ eine Änderung vorgenommen hat, die zu einem Konflikt im Pull-Request führt. Gehen wir diese Schritte einzeln durch.

Sobald du das getan hast, wird der Pull-Request automatisch aktualisiert und erneut überprüft, um festzustellen, ob er sauber zusammengeführt werden kann.

Einer der großen Pluspunkte von Git ist, dass man das kontinuierlich tun kann. Wenn du ein sehr lang laufendes Projekt hast, könntest du leicht immer wieder aus dem Zielbranch heraus mergen und müsstest dich nur mit Konflikten befassen, die seit dem letzten Mal, als du zusammengeführt hast, aufgetreten sind; was den Prozess sehr überschaubar macht.

Wenn du den Branch unbedingt rebasen willst, um ihn aufzuräumen, könntest du das natürlich tun. Es wird jedoch dringend empfohlen, den Branch, auf dem der Pull-Request bereits geöffnet ist, nicht zu force-pushen. Wenn von Anderen gepullt wurde und weitere Arbeiten daran durchgeführt wurden, stößt man auf alle in Kapitel 3, Die Gefahren des Rebasing beschriebenen Probleme. Schiebe stattdessen den rebasten Branch zu einem neuen Branch auf GitHub und öffne einen brandneuen Pull Request mit Bezug auf den alten Branch und schließen den originalen Pull Request.

Möglicherweise lautet deine nächste Frage: „Wie verweise ich auf den alten Pull-Request?“. Es stellt sich heraus, dass es viele, viele Möglichkeiten gibt, auf andere Dinge Bezug zu nehmen, und zwar fast überall dort, wo man in GitHub schreiben kann.

Beginnen wir mit der Frage, wie man einen anderen Pull-Request oder ein Issue vergleicht. Alle Pull-Requests und Issues sind mit Nummern versehen und innerhalb des Projekts eindeutig. Beispielsweise ist es nicht möglich, Pull Request #3 und Issue #3 anzulegen. Wenn du auf einen Pull-Request oder ein Issue von einem anderen verweisen möchtest, kannst du einfach <num> in einen Kommentar oder eine Beschreibung eingeben. Du kannst auch präziser sein, wenn die Issue- oder Pull-Anforderung an einem anderen Ort liegen. Schreibe Benutzername<num>, wenn du dich auf ein Issue oder Pull Request beziehst, in einen Fork des Repositorys, in dem du dich befindest. Oder schreibe Benutzername/repo#<num>, um auf etwas in einem anderen Repository zu verweisen.

Schauen wir uns ein Beispiel an. Angenommen, wir haben den Branch aus dem vorherigen Beispiel rebased, einen neuen Pull-Request für ihn erstellt und jetzt wollen wir die alte Pull-Anforderung aus der neuen aufrufen. Wir möchten auch auf ein Problem im Fork des Repositorys und auf ein Problem in einem ganz anderen Projekt verweisen. Wir können die Beschreibung wie bei Querverweise in einem Pull-Request eingeben.

Wenn wir diese Pull-Anfrage einreichen, werden wir sehen, dass alles wie in „Querverweise, die in einem Pull-Request erzeugt wurden“ dargestellt wird.

Bitte beachte, dass die vollständige GitHub-URL, die wir dort eingegeben haben, auf die benötigten Informationen gekürzt wurde.

Wenn Tony nun zurück geht und den ursprünglichen Pull-Request schließt, können wir sehen, dass GitHub automatisch ein Trackback-Ereignis in der Pull-Request Zeitleiste erstellt hat, indem er ihn im neuen Pull-Request erwähnt. Das bedeutet, dass jeder, der diesen Pull-Request aufruft, sieht, dass er geschlossen ist. Er kann leicht auf denjenigen zurückgreifen, der ihn ersetzt hat. Der Link wird in etwa wie in „Zurück zum neuen Pull-Request in der geschlossenen Pull-Request Zeitleiste“ aussehen.

Zusätzlich zu den Issue-Nummern kannst du auch auf einen bestimmten Commit per SHA-1 referenzieren. Du musst einen vollen 40-stelligen SHA-1 angeben. Wenn GitHub das in einem Kommentar sieht, wird er direkt auf den Commit verlinken. Wie bei Issues kannst du auch hier auf Commits in Forks oder anderen Repositorys verweisen.

Die wirklich praktische GitHub-spezifische Markdown-Funktion, vor allem für die Verwendung in Pull-Requests, ist die Aufgabenliste. Eine Aufgabenliste ist eine Liste von Kontrollkästchen für alle Vorgänge, die du erledigen möchtest. Wenn du sie in einen Issue oder Pull-Request einfügst, werden normalerweise Punkte angezeigt, die du erledigen sollst, bevor du den gesamten Vorgang als erledigt betrachten kannst.

Du kannst eine Task-Liste wie folgt anlegen:

Wenn wir das in die Beschreibung unseres Pull Request oder Issue aufnehmen, sehen wir, dass es wie in Aufgabenliste in Markdown-Kommentar, gerendert dargestellt wird.

Diese Funktion wird häufig in Pull Requests verwendet, um zu verdeutlichen, was du alles auf dem Branch erledigen möchtest, bevor der Pull Request bereit für die Zusammenführung ist. Der wirklich coole Teil ist, dass du einfach auf die Kontrollkästchen klicken kannst, um den Kommentar zu aktualisieren. Du musst nicht den Markdown bearbeiten, um Aufgaben als erledigt zu markieren.

Darüber hinaus sucht GitHub nach Aufgabenlisten in deinen Issues und Pull Requests und zeigt sie als Metadaten zu den Seiten an, auf denen sie stehen. Wenn du z.B. einen Pull-Request mit Aufgabenliste hast und dir die Übersichtsseite aller Pull-Requests ansiehst, kannst du sehen, wie weit er abgearbeitet ist. Das hilft den Teilnehmern, Pull-Requests in Teilaufgaben aufzuschlüsseln und anderen Teilnehmern, den Fortschritt des Branch zu verfolgen. Ein Beispiel dafür findest du bei: Task-Liste (Zusammenfassung) in der Pull-Request-Liste.

Diese Funktion ist unglaublich nützlich, wenn du einen Pull Request frühzeitig öffnest und damit deinen Fortschritt bei der Realisierung des Features verfolgst (engl. track).

Du kannst auch Code-Schnipsel zu Kommentaren hinzufügen. Es ist dann besonders praktisch, wenn du etwas präsentieren möchtest, das du versuchen könntest, bevor du es tatsächlich als Commit auf deinem Branch einbaust. Das wird auch oft verwendet, um Beispielcode hinzuzufügen, der verrät, was nicht funktioniert oder was dieser Pull-Request umsetzen könnte.

Um ein Code-Schnipsel hinzuzufügen, musst du ihn in zwei 3-fach Backticks (`) „einzäunen“.

Wenn du den Namen der Programmiersprache hinzufügst, wie wir es mit java getan haben, wird GitHub versuchen, die Syntax hervorzuheben. Wie im Beispiel oben, würde es zu „eingezäuntes“, gerendertes Code-Schnipsel-Beispiel gerendert werden.

Wenn du auf einen kleinen Teil eines langen Kommentars reagieren willst, kannst du selektiv aus dem anderen Kommentar zitieren, indem du den Zeilen das Zeichen > voranstellst. Es ist sogar so häufig und nützlich, dass es eine Tastenkombination dafür gibt. Wenn du Text in einem Kommentar markierst, auf den du direkt antworten möchtest, und die Taste r drückst, wird dieser Text in der Kommentarbox für dich zitiert.

Zitate (engl. quotes) sehen in etwa so aus:

Nach dem Rendern sieht der Kommentar wie folgt aus: gerendertes Zitat-Beispiel.

Abschließend kannst du auch Emojis in deinen Kommentaren verwenden. Das wird in der Praxis sehr häufig verwendet. Du wirst es in vielen GitHub-Issues und Pull-Requests sehen. Es gibt sogar einen Emoji-Helfer in GitHub. Wenn du einen Kommentar eingibst und mit einem : (Doppelpunkt) beginnst, hilft dir ein Autokomplettierer, das Gesuchte schnell zu finden.

Emojis haben die Erscheinungsform von :<name>: irgendwo im Kommentar. Zum Beispiel kannst du so etwas schreiben:

Gerendert würde es in etwa so aussehen: Massive Emoji-Kommentare.

Nicht, dass das äußerst sinnvoll wäre, aber es ergänzt ein Medium mit Spaß und Emotionen, was sonst nur schwer zu vermitteln wäre.

Technisch gesehen ist das keine GitHub-Variante von Markdown, aber es ist sehr praktisch. Neben dem Hinzufügen von Markdown-Bildlinks zu Kommentaren, für die es schwierig sein kann, URLs zum Einbetten zu finden, kannst du mit GitHub Bilder per Drag&Drop in Textbereiche ziehen und so einbinden.

Wenn du dir Bilder per Drag&Drop hochladen und automatisch einbetten ansiehst, wirst du einen kleinen Hinweis, „Parsed as Markdown“, über dem Textfeld sehen. Wenn du darauf klickst, erhältst du einen vollständiges Cheat-Sheet (Spickzettel) mit allem, was du mit Markdown auf GitHub machen kannst.