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. Lassen Sie uns also das Programm verbessern und es als Änderungsvorschlag an das Projekt zurücksenden.

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 Themenzweig erstellen, den Code ändern und schließlich diese Änderung wieder auf GitHub übertragen.

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

Sie können alternativ auch die Seite „Branches“ bei https://github.com/<user>/<project>/branches aufzurufen, um Ihre 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 Sie aufgefordert werden, Ihrem Pull Request einen Titel und eine Beschreibung zu geben. Es ist fast immer sinnvoll, sich ein bisschen Mühe zu geben, da eine gute Beschreibung dem Eigentümer des ursprünglichen Projekts hilft, festzustellen, was Sie versucht haben, ob Ihre vorgeschlagenen Änderungen korrekt sind und ob die Annahme der Änderungen das ursprüngliche Projekt verbessern würde.

Wir erhalten auch eine Liste der Commits in unserem Themen-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 gemergt wird.

Wenn Sie in diesem Fenster auf die Schaltfläche 'Create pull request' klicken, wird der Eigentümer/Leiter des Projekts, für das Sie eine Abspaltung (engl. Fork) vorgenommen haben, benachrichtigt, 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. Sie sehen, dass auch die Code-Kommentare in das Diskussionsfenster eingebracht werden.

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

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 Sie den „vereinheitlichten“ Diff erhalten, wenn Sie auf die Registerkarte „Files Changed“ in diesem Pull-Request klicken – d.h. die gesamte aggregierte Differenz, die in Ihren Hauptbranch eingebracht würde, wenn dieser Themenzweig gemergt würde. Im Sinne von git diff zeigt es Ihnen 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 Diff.

Außerdem prüft GitHub, ob der Pull-Request sauber mergen würde und stellt eine Schaltfläche zur Verfügung, mit der Sie den Merge auf dem Server durchführen können. Diese Schaltfläche erscheint nur, wenn Sie Schreibzugriff auf das Repository haben und ein trivialer Merge möglich ist. Wenn Sie darauf klicken, 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 Sie möchten, können Sie den Branch einfach herunterladen (engl. pull) und lokal zusammenführen (engl. merge). Wenn Sie diesen Zweig mit dem master Branch verschmelzen und ihn nach GitHub pushen, wird der Pull Request automatisch geschlossen.

Das ist der grundsätzliche Workflow, den die meisten GitHub-Projekte verwenden. Themen-Branches werden erstellt, Pull-Requests werden geöffnet, es folgt eine Diskussion, möglicherweise wird eine weitere Überarbeitung des Zweiges 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, wobei die meisten Mailinglisten-basierten Projekte an Patch-Serienbeiträge denken. Die meisten GitHub-Projekte betrachten Pull-Request-Branches als iterative Dialoge um eine beabsichtigte Änderung, die zu einem vereinheitlichten Diff führt, welches durch das Mergen angewendet wird.

Das ist ein wichtiger Unterschied, denn im Allgemeinen wird die Änderung vorgeschlagen, bevor der Code perfektioniert ist, was bei Beiträgen von Patch-Serien auf Mailinglistenbasis weitaus seltener ist. So kann früher mit den Betreuern gesprochen werden, damit die richtige Lösung eher eine Gemeinschaftsarbeit ist. 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, sondern der Unterschied wird als neuer Commit an den Branch weitergegeben (gepusht), wodurch der Dialog im intakten Kontext der vorherigen Arbeit fortgesetzt wird.

Wenn Sie beispielsweise zurückgehen und sich den finalen Pull-Request erneut ansehen, werden Sie feststellen, dass der Beitragende seinen Commit nicht umbasiert hat (engl. rebase) und einen weiteren Pull-Request geöffnet hat. Stattdessen wurden neue Commits hinzugefügt und sie in den bestehenden Zweig gepusht. Wenn Sie also in Zukunft auf diesen Pull Request zurückblicken, können Sie leicht den gesamten Kontext finden, in dem die Entscheidungen getroffen wurden. Wenn Sie auf der Website auf die Schaltfläche „Merge“ klicken, wird gezielt ein Merge-Commit erstellt, der auf den Pull-Request verweist, so dass Sie leicht zurückkehren und bei Bedarf die ursprüngliche Diskussion durchsuchen können.

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

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

Sie haben zwei grundsätzliche Möglichkeiten, wie Sie das realisieren können. Sie können Ihren Branch entweder auf den Ziel-Branch rebasen (normalerweise den master Branch des von Ihnen geforkten Repositorys), oder Sie können den Ziel-Branch mit Ihrem 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 Sie im Ziel-Branch mergen wollen, um Ihren Pull-Request zusammenzuführen zu können, sollten Sie das ursprüngliche Repository als neuen Remote hinzufügen. Dann machen Sie ein git fetch davon, führen den Hauptzweig dieses Repositorys in Ihren Themen-Branch zusammen, beheben alle Probleme und pushen Sie es schließlich wieder in den gleichen Branch, in dem Sie den Pull-Request geöffnet hatten.

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 Sie das getan haben, 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 Sie ein sehr lang laufendes Projekt haben, können Sie leicht immer wieder aus dem Zielbranch heraus mergen und müssen sich nur mit Konflikten befassen, die seit dem letzten Mal, als Sie zusammengeführt haben, aufgetreten sind; was den Prozess sehr überschaubar macht.

Wenn Sie den Branch unbedingt rebasen wollen, um ihn aufzuräumen, können Sie das natürlich tun, aber es wird dringend empfohlen, den Branch, auf dem der Pull-Request bereits geöffnet ist, nicht zwangsweise zu 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. Schieben Sie stattdessen den rebasierten Branch zu einem neuen Branch auf GitHub und öffnen Sie einen brandneuen Pull Request mit Bezug auf den alten Branch und schließen Sie dann das Original.

Möglicherweise lautet Ihre 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 Sie auf einen Pull-Request oder ein Issue von einem anderen verweisen möchten, können Sie einfach <num> in einen Kommentar oder eine Beschreibung eingeben. Sie können auch präziser sein, wenn die Issue- oder Pull-Anforderung an einem anderen Ort liegt; schreiben Sie Benutzername<num>, wenn Sie sich auf ein Issue oder Pull Request beziehen, in einen Fork des Repositorys, in dem Sie sich befinden, oder 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 rebasiert, 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 in der 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 beachten Sie, 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 können Sie auch auf einen bestimmten Commit per SHA-1 referenzieren. Sie müssen einen vollen 40-stelligen SHA-1 angeben, aber wenn GitHub das in einem Kommentar sieht, wird er direkt auf den Commit verlinken. Wie bei Issues können Sie 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 Sie erledigen möchten. Wenn Sie sie in einen Issue oder Pull-Request einfügen, werden normalerweise Punkte angezeigt, die Sie erledigen sollten, bevor Sie den Vorgang als erledigt betrachten.

Sie können 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 alles Sie auf dem Branch erledigen möchten, bevor der Pull Request bereit für die Zusammenführung ist. Der wirklich coole Teil ist, dass Sie einfach auf die Kontrollkästchen klicken können, um den Kommentar zu aktualisieren – Sie müssen den Markdown nicht direkt bearbeiten, um Aufgaben als erledigt zu markieren.

Darüber hinaus sucht GitHub nach Aufgabenlisten in Ihren Issues und Pull Requests und zeigt sie als Metadaten zu den Seiten, auf denen sie stehen, an. Wenn Sie z.B. einen Pull-Request mit Aufgabenliste haben und sich die Übersichtsseite aller Pull-Requests ansehen, können Sie sehen, wie weit er abgearbeitet ist. Das hilft den Teilnehmern, Pull-Requests in Teilaufgaben aufzuschlüsseln und anderen Teilnehmern, den Fortschritt der Branch zu verfolgen. Ein Beispiel dafür finden Sie bei: Task-Liste (Zusammenfassung) in der Pull-Request-Liste.

Diese Funktion ist unglaublich nützlich, wenn Sie einen Pull Request frühzeitig öffnen und damit Ihren Fortschritt bei der Realisierung des Features verfolgen (engl. track).

Sie können auch Code-Schnipsel zu Kommentaren hinzufügen. Es ist dann besonders praktisch, wenn Sie etwas präsentieren möchten, das Sie versuchen könnten, bevor Sie es tatsächlich als Commit auf Ihrem Branch einbauen. 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, müssen Sie ihn in zwei 3-fach Backticks (`) „einzäunen“.

Wenn Sie den Namen der Programmiersprache hinzufügen, 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 Sie auf einen kleinen Teil eines langen Kommentars reagieren wollen, können Sie selektiv aus dem anderen Kommentar zitieren, indem Sie den Zeilen das Zeichen > voranstellen. Es ist sogar so häufig und nützlich, dass es eine Tastenkombination dafür gibt. Wenn Sie Text in einem Kommentar markieren, auf den Sie direkt antworten möchten, und die Taste r drücken, wird dieser Text in der Kommentarbox für Sie zitiert.

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

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

Abschließend, Sie können auch Emojis in Ihren Kommentaren verwenden. Das wird in der Praxis sehr häufig in Kommentaren verwendet. Sie werden es in vielen GitHub-Issues und Pull-Requests sehen. Es gibt sogar einen Emoji-Helfer in GitHub. Wenn Sie einen Kommentar eingeben und mit einem : (Doppelpunkt) beginnen, hilft Ihnen ein Autokomplettierer, das Gesuchte schnell zu finden.

Emojis haben die Erscheinungsform von :<name>: irgendwo im Kommentar. Zum Beispiel könnten Sie so ähnlich wie hier 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 unglaublich praktisch. Neben dem Hinzufügen von Markdown-Bildlinks zu Kommentaren, für die es schwierig sein kann, URLs zum Einbetten zu finden, können Sie mit GitHub Bilder per Drag&Drop in Textbereiche ziehen und so einbinden.

Wenn Sie sich Bilder per Drag&Drop hochladen und automatisch einbetten ansehen, werden Sie einen kleinen Hinweis, „Parsed as Markdown“, über dem Textfeld sehen. Wenn Sie darauf klicken, erhalten Sie einen vollständigen Cheat-Sheet (Spickzettel) mit allem, was Sie mit Markdown auf GitHub machen können.