6.2 GitHub - Beitrag zu einem Projekt

Tony sucht nach Code, den er auf seinem programmierbaren Arduino-Mikrocontroller ausführen kann, und hat eine großartige Programmdatei auf GitHub unter https://github.com/schacon/blink gefunden.

Das einzige Problem ist, dass die Blinkrate zu hoch ist. Wir finden es viel schöner, 3 Sekunden statt 1 Sekunde zwischen den Zustandswechseln zu warten. Lassen Sie uns das Programm also verbessern und es als vorgeschlagene Änderung an das Projekt zurücksenden.

Zuerst klicken wir auf die Schaltfläche "Fork", wie oben erwähnt, um unsere eigene Kopie des Projekts zu erhalten. Unser Benutzername hier ist "tonychacon", also befindet sich unsere Kopie dieses Projekts unter https://github.com/tonychacon/blink, und dort können wir es bearbeiten. Wir werden es lokal klonen, einen Topic-Branch erstellen, die Codeänderung vornehmen und diese Änderung schließlich wieder auf GitHub pushen.

Wenn wir nun zu unserem Fork auf GitHub zurückkehren, sehen wir, dass GitHub bemerkt hat, dass wir einen neuen Topic-Branch hochgeladen haben, und uns eine große grüne Schaltfläche anzeigt, um unsere Änderungen zu überprüfen und einen Pull-Request an das ursprüngliche Projekt zu öffnen.

Alternativ können Sie die Seite "Branches" unter https://github.com/<user>/<project>/branches besuchen, um Ihren Branch zu finden und von dort aus einen neuen Pull-Request zu öffnen.

Wenn wir auf diese grüne Schaltfläche klicken, sehen wir einen Bildschirm, auf dem wir aufgefordert werden, unserem Pull-Request einen Titel und eine Beschreibung zu geben. Es lohnt sich fast immer, sich Mühe zu geben, da eine gute Beschreibung dem Eigentümer des ursprünglichen Projekts hilft zu bestimmen, was Sie zu tun versucht haben, ob Ihre vorgeschlagenen Änderungen korrekt sind und ob die Annahme der Änderungen das ursprüngliche Projekt verbessern würde.

Wir sehen auch eine Liste der Commits in unserem Topic-Branch, die sich "vor" dem master-Branch befinden (in diesem Fall nur einer) und einen einheitlichen Diff aller Änderungen, die vorgenommen werden, wenn dieser Branch vom Projekteigentümer gemergt wird.

Wenn Sie auf dieser Seite auf die Schaltfläche "Create pull request" klicken, erhält der Eigentümer des Projekts, das Sie geforkt haben, eine Benachrichtigung, dass jemand eine Änderung vorschlägt, und wird zu einer Seite weitergeleitet, auf der all diese Informationen enthalten sind.

An diesem Punkt kann der Projekteigentümer die vorgeschlagene Änderung prüfen und sie mergen, ablehnen oder kommentieren. Nehmen wir an, ihm gefällt die Idee, aber er bevorzugt eine etwas längere Wartezeit, in der das Licht aus ist, als dass es an ist.

Wo diese Unterhaltung in den in Distributed Git vorgestellten Workflows per E-Mail stattfinden mag, geschieht dies auf GitHub online. Der Projekteigentümer kann den einheitlichen Diff überprüfen und durch Klicken auf eine beliebige Zeile einen Kommentar hinterlassen.

Sobald der Maintainer diesen Kommentar abgibt, erhält die Person, die den Pull-Request geöffnet hat (und tatsächlich jeder andere, der das Repository beobachtet), eine Benachrichtigung. Wir werden die Anpassung später behandeln, aber wenn er E-Mail-Benachrichtigungen aktiviert hätte, würde Tony eine E-Mail wie diese erhalten

Jeder kann auch allgemeine Kommentare zum Pull-Request hinterlassen. Auf der Pull-Request-Diskussionsseite sehen wir ein Beispiel dafür, wie der Projekteigentümer sowohl einen Kommentar zu einer Codezeile abgibt als auch einen allgemeinen Kommentar im Diskussionsbereich hinterlässt. Sie können sehen, dass die Code-Kommentare auch in die Unterhaltung einbezogen werden.

Nun kann der Mitwirkende sehen, was er tun muss, um seine Änderung akzeptiert zu bekommen. Glücklicherweise ist dies sehr einfach. Wo Sie per E-Mail Ihre Serie neu aufrollen und an die Mailingliste zurücksenden müssten, committen Sie mit GitHub einfach erneut in den Topic-Branch und pushen, was den Pull-Request automatisch aktualisiert. In Pull Request final sehen Sie auch, dass der alte Code-Kommentar im aktualisierten Pull-Request eingeklappt wurde, da er sich auf eine Zeile bezog, die seitdem geändert wurde.

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

Interessant ist, dass Sie, wenn Sie auf den Tab "Files Changed" in diesem Pull-Request klicken, den "einheitlichen" Diff erhalten - das heißt, die gesamte aggregierte Differenz, die in Ihren Haupt-Branch eingeführt würde, wenn dieser Topic-Branch gemergt würde. In git diff-Begriffen zeigt er Ihnen im Grunde automatisch git diff master…<branch> für den Branch, auf dem dieser Pull-Request basiert. Weitere Informationen zu dieser Art von Diff finden Sie unter Bestimmen, was eingeführt wird.

Das andere, was Ihnen auffallen wird, ist, dass GitHub prüft, ob der Pull-Request sauber mergt und eine Schaltfläche bereitstellt, um den Merge für Sie auf dem Server durchzuführen. Diese Schaltfläche wird nur angezeigt, 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 der Merge ein Fast-Forward sein könnte, immer noch ein Merge-Commit erstellt wird.

Wenn Sie möchten, können Sie den Branch auch einfach herunterziehen und lokal mergen. Wenn Sie diesen Branch in den master-Branch mergen und auf GitHub pushen, wird der Pull-Request automatisch geschlossen.

Dies ist der grundlegende Workflow, den die meisten GitHub-Projekte verwenden. Topic-Branches werden erstellt, Pull-Requests werden darauf geöffnet, eine Diskussion folgt, möglicherweise werden weitere Arbeiten am Branch durchgeführt und schließlich wird die Anfrage entweder geschlossen oder gemergt.

Es ist wichtig zu verstehen, dass viele Projekte Pull-Requests nicht wirklich als Reihen von perfekten Patches betrachten, die sauber und in Ordnung angewendet werden sollten, so wie es bei den meisten auf Mailinglisten basierenden Projekten der Fall ist. Die meisten GitHub-Projekte betrachten Pull-Request-Branches als iterative Konversationen rund um eine vorgeschlagene Änderung, die in einem einheitlichen Diff gipfeln, der durch Mergen angewendet wird.

Dies ist eine wichtige Unterscheidung, da die Änderung im Allgemeinen vorgeschlagen wird, bevor der Code als perfekt erachtet wird, was bei auf Mailinglisten basierenden Patch-Serienbeiträgen weitaus seltener vorkommt. Dies ermöglicht eine frühere Konversation mit den Maintainern, so dass das Erreichen der richtigen Lösung eher zu einer Gemeinschaftsleistung wird. 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 stattdessen wird die Differenz als neuer Commit in den Branch gepusht, was die Konversation mit dem Kontext der bisherigen Arbeit beibehält.

Wenn Sie beispielsweise noch einmal zu Pull Request final zurückkehren, werden Sie feststellen, dass der Mitwirkende seinen Commit nicht neu aufgerollt und einen weiteren Pull-Request gesendet hat. Stattdessen hat er neue Commits hinzugefügt und sie in den bestehenden Branch gepusht. Auf diese Weise können Sie, wenn Sie diesen Pull-Request in Zukunft noch einmal ansehen, leicht den gesamten Kontext finden, warum Entscheidungen getroffen wurden. Das Drücken der "Merge"-Schaltfläche auf der Website erstellt absichtlich einen Merge-Commit, der auf den Pull-Request verweist, so dass es einfach ist, die ursprüngliche Konversation bei Bedarf zu recherchieren.

Wenn Ihr Pull-Request veraltet ist oder anderweitig nicht sauber mergt, sollten Sie ihn reparieren, damit der Maintainer ihn problemlos mergen kann. GitHub testet dies für Sie und teilt Ihnen am Ende jedes Pull-Requests mit, ob der Merge trivial ist oder nicht.

Wenn Sie etwas wie Pull-Request mergt nicht sauber sehen, sollten Sie Ihren Branch reparieren, damit er grün wird und der Maintainer keine zusätzliche Arbeit hat.

Sie haben zwei Hauptoptionen, um dies zu tun. Sie können entweder Ihren Branch auf dem Ziel-Branch neu aufrollen (normalerweise der master-Branch des Repositorys, das Sie geforkt haben) oder Sie können den Ziel-Branch in Ihren Branch mergen.

Die meisten Entwickler auf GitHub werden sich für Letzteres entscheiden, aus denselben Gründen, die wir gerade im vorherigen Abschnitt besprochen haben. Was zählt, ist die Historie und der endgültige Merge, daher bringt Ihnen das Neuaufrollen nicht viel mehr als eine etwas sauberere Historie und ist im Gegenzug **weitaus** schwieriger und fehleranfälliger.

Wenn Sie den Ziel-Branch mergen möchten, um Ihren Pull-Request mergbar zu machen, würden Sie das ursprüngliche Repository als neues Remote hinzufügen, davon fetchen, den Haupt-Branch dieses Repositorys in Ihren Topic-Branch mergen, alle Probleme beheben und ihn schließlich wieder auf denselben Branch pushen, auf dem Sie den Pull-Request geöffnet haben.

Nehmen wir zum Beispiel an, dass im "tonychacon"-Beispiel, das wir zuvor verwendet haben, der ursprüngliche Autor eine Änderung vorgenommen hat, die einen Konflikt im Pull-Request verursachen würde. Gehen wir diese Schritte durch.

Sobald Sie dies getan haben, wird der Pull-Request automatisch aktualisiert und erneut geprüft, ob er sauber mergt.

Eines der großartigen Dinge an Git ist, dass Sie dies kontinuierlich tun können. Wenn Sie ein sehr lang laufendes Projekt haben, können Sie problemlos immer wieder vom Ziel-Branch mergen und nur Konflikte beheben, die seit dem letzten Merge aufgetreten sind, was den Prozess sehr überschaubar macht.

Wenn Sie den Branch unbedingt neu aufrollen möchten, um ihn zu bereinigen, können Sie dies natürlich tun, aber es wird dringend davon abgeraten, über den Branch zu forcieren, auf dem der Pull-Request bereits geöffnet ist. Wenn andere Leute ihn heruntergezogen und weitere Arbeit daran geleistet haben, treten alle Probleme auf, die in The Perils of Rebasing beschrieben sind. Pushen Sie stattdessen den neu aufgerollten Branch in einen neuen Branch auf GitHub und öffnen Sie einen brandneuen Pull-Request, der den alten referenziert, und schließen Sie dann den ursprünglichen.

Ihre nächste Frage könnte sein: "Wie referenziere ich den alten Pull-Request?". Es stellt sich heraus, dass es viele, viele Möglichkeiten gibt, andere Dinge fast überall zu referenzieren, wo Sie auf GitHub schreiben können.

Beginnen wir damit, wie man einen anderen Pull-Request oder ein Issue referenziert. Alle Pull-Requests und Issues erhalten Nummern und sind innerhalb des Projekts eindeutig. Sie können zum Beispiel nicht Pull-Request #3 *und* Issue #3 haben. Wenn Sie einen Pull-Request oder ein Issue von einem anderen referenzieren möchten, können Sie einfach #<num> in einen Kommentar oder eine Beschreibung einfügen. Sie können auch spezifischer sein, wenn das Issue oder der Pull-Request woanders liegt; schreiben Sie username#<num>, wenn Sie sich auf ein Issue oder einen Pull-Request in einem Fork des Repositorys beziehen, in dem Sie sich befinden, oder username/repo#<num>, um etwas in einem anderen Repository zu referenzieren.

Sehen wir uns ein Beispiel an. Nehmen wir an, wir haben den Branch im vorherigen Beispiel neu aufgerollt, einen neuen Pull-Request dafür erstellt und möchten nun den alten Pull-Request aus dem neuen referenzieren. Wir möchten auch auf ein Issue im Fork des Repositorys und ein Issue in einem völlig anderen Projekt verweisen. Wir können die Beschreibung wie in Cross references in a Pull Request ausfüllen.

Wenn wir diesen Pull-Request einreichen, sehen wir all dies gerendert, wie in Cross references rendered in a Pull Request.

Beachten Sie, dass die vollständige GitHub-URL, die wir dort eingegeben haben, auf die Informationen gekürzt wurde, die benötigt werden.

Wenn Tony nun zurückgeht und den ursprünglichen Pull-Request schließt, können wir sehen, dass GitHub durch die Erwähnung im neuen Pull-Request automatisch ein Trackback-Ereignis in der Timeline des Pull-Requests erstellt hat. Das bedeutet, dass jeder, der diesen Pull-Request besucht und sieht, dass er geschlossen ist, leicht zu dem zurückverlinken kann, der ihn abgelöst hat. Der Link sieht ungefähr so aus, wie in Link back to the new Pull Request in the closed Pull Request timeline.

Zusätzlich zu Issue-Nummern können Sie auch einen bestimmten Commit mit SHA-1 referenzieren. Sie müssen eine vollständige 40-stellige SHA-1-Nummer angeben, aber wenn GitHub diese in einem Kommentar sieht, wird sie direkt auf den Commit verlinken. Auch hier können Sie Commits in Forks oder anderen Repositories auf dieselbe Weise referenzieren wie Issues.

Das erste wirklich nützliche, GitHub-spezifische Markdown-Feature, insbesondere für die Verwendung in Pull-Requests, ist die Aufgabenliste. Eine Aufgabenliste ist eine Liste von Checkboxen mit Dingen, die Sie erledigen möchten. Das Einfügen in ein Issue oder einen Pull-Request zeigt normalerweise Dinge an, die Sie erledigen möchten, bevor Sie den Punkt als abgeschlossen betrachten.

Sie können eine Aufgabenliste wie folgt erstellen

Wenn wir dies in die Beschreibung unseres Pull-Requests oder Issues aufnehmen, sehen wir es gerendert, wie in Task lists rendered in a Markdown comment.

Dies wird oft in Pull-Requests verwendet, um anzuzeigen, was alles erledigt werden soll, bevor der Pull-Request zum Mergen bereit ist. Der wirklich coole Teil ist, dass Sie einfach auf die Checkboxen klicken können, um den Kommentar zu aktualisieren – Sie müssen das Markdown nicht direkt bearbeiten, um Aufgaben abzuhaken.

Darüber hinaus sucht GitHub nach Aufgabenlisten in Ihren Issues und Pull-Requests und zeigt sie als Metadaten auf den Seiten an, die sie auflisten. Wenn Sie beispielsweise einen Pull-Request mit Aufgaben haben und sich die Übersichtsseite aller Pull-Requests ansehen, können Sie sehen, wie weit er fortgeschritten ist. Dies hilft den Leuten, Pull-Requests in Unteraufgaben aufzuteilen und hilft anderen, den Fortschritt des Branches zu verfolgen. Ein Beispiel dafür sehen Sie in Task list summary in the Pull Request list.

Diese sind unglaublich nützlich, wenn Sie einen Pull-Request frühzeitig öffnen und ihn verwenden, um Ihren Fortschritt bei der Implementierung des Features zu verfolgen.

Sie können auch Code-Snippets zu Kommentaren hinzufügen. Dies ist besonders nützlich, wenn Sie etwas präsentieren möchten, das Sie versuchen *könnten*, zu tun, bevor Sie es tatsächlich als Commit auf Ihrem Branch implementieren. Dies wird auch oft verwendet, um Beispielcode hinzuzufügen, der nicht funktioniert oder was dieser Pull-Request implementieren könnte.

Um ein Code-Snippet hinzuzufügen, müssen Sie es mit Backticks "einfrieden".

Wenn Sie einen Sprachnamen hinzufügen, wie wir es dort mit 'java' getan haben, wird GitHub auch versuchen, das Snippet syntaktisch hervorzuheben. Im Fall des obigen Beispiels würde es gerendert, wie in Rendered fenced code example.

Wenn Sie auf einen kleinen Teil eines langen Kommentars antworten, können Sie selektiv aus dem anderen Kommentar zitieren, indem Sie die Zeilen mit dem Zeichen > versehen. Tatsächlich ist dies so üblich und so nützlich, dass es eine Tastenkombination dafür gibt. Wenn Sie Text in einem Kommentar hervorheben, auf den Sie direkt antworten möchten, und die Taste r drücken, wird dieser Text in das Kommentarfeld für Sie zitiert.

Die Zitate sehen ungefähr so aus

Sobald gerendert, sieht der Kommentar aus wie in Rendered quoting example.

Schließlich können Sie auch Emoji in Ihren Kommentaren verwenden. Dies wird tatsächlich recht häufig in Kommentaren verwendet, die Sie in vielen GitHub Issues und Pull-Requests sehen. Es gibt sogar eine Emoji-Hilfe in GitHub. Wenn Sie einen Kommentar tippen und mit einem :-Zeichen beginnen, hilft Ihnen ein Autocompleter, das Gesuchte zu finden.

Emojis haben die Form von :<name>: irgendwo im Kommentar. Zum Beispiel könnten Sie etwas wie folgt schreiben

Wenn es gerendert wird, sieht es ungefähr so aus wie in Heavy emoji commenting.

Nicht dass dies unglaublich nützlich ist, aber es fügt ein Element von Spaß und Emotion zu einem Medium hinzu, in dem Emotionen sonst schwer zu vermitteln sind.

Dies ist technisch gesehen kein GitHub Flavored Markdown, aber es ist unglaublich nützlich. Zusätzlich zum Hinzufügen von Markdown-Bildlinks zu Kommentaren, bei denen es schwierig sein kann, URLs zu finden und einzubetten, erlaubt GitHub Ihnen, Bilder in Textbereiche zu ziehen und abzulegen, um sie einzubetten.

Wenn Sie sich Drag and drop images to upload them and auto-embed them ansehen, sehen Sie einen kleinen Hinweis "Parsed as Markdown" über dem Textbereich. Wenn Sie darauf klicken, erhalten Sie eine vollständige Cheat-Sheet mit allem, was Sie mit Markdown auf GitHub tun können.