Wie man Git(Hub)t

Wenn du beim programmieren von Sponge mithelfen möchtest, eine großartige Idee für die API hast oder unsere Dokumentation verbessern möchtest, dann musst du dich mit Git und GitHub vertraut machen. Wenn du dich bereits mit dem Forken, den Branches, pull-requests und Commits auskennst, dann kannst du diese Seite überspringen. Falls du keine Ahnung hast, was diese Begriffe bedeuten, lies weiter.

Bemerkung

This guide assumes that you’ve read Git installieren and that you’ve already setup your machine with a Git client of your choice.

Das Grundkonzept von Git und GitHub

Git ermöglicht die gleichzeitige, gemeinsame Arbeit von vielen Entwicklern an einem einzigen Stück Software. GitHub ist eine Website auf der Entwickler zusammenarbeiten und ihre Arbeit untereinander teilen können. GitHub beruht auf Git, als Tool für die Verwaltung der Projekte.

Tipp

Wenn du mit dem Vokabular von Git und GitHub nicht vertraut bist, kannst du einen Blick auf die Glossar Seite auf GitHub werfen.

Repo Overview

In diesem Fall heißt das Repository SpongePowered und beinhaltet die zwei Branches master und feature1 sowie einige Commits in beiden Branches.

Um diese Begriffe in einen Kontext zu setzen - beginnend mit dem Repostiory: Das Repository (kurz: Repo) ist der Ort, an dem alle Dateien eines Projekts gespeichert sind. Die SpongePowered-Repositories befinden sich bei GitHub. Jedoch hat das Repository einige Zugriffseinschränkungen, um es vor unerwünschten oder schädlichen Änderungen zu schützen. Man kann also nicht einfach so selbst Änderungen machen, weil normale Benutzer nur Leserecht für das Repository haben. Jetzt fragen Sie sich vielleicht, wie Sie Vorschläge und Änderungen einreichen sollen. Das ist der Punkt, an dem Forks ins spiel kommen. Sie können einfach eine Kopie der SpongePowered-Repositories machen und dort Ihre Änderungen vornehmen. Wenn Sie fertig sind, öffnen Sie ihr Repository als Pull-Request (PR) bei unserem Repository. Ihre vorgeschlagenen Hinzufügungen und Änderungen können dann angesehen werden und das Personal wird ihnen Bescheid geben, wenn etwas falsch ist oder Verbesserungen benötigt und eventuell sogar den finalen Pull-Request mergen.

Hier eine kurze Zusammenfassung von dem oben beschriebenen Ablauf, bevor wir ins Detail gehen:

  1. „fork“ (deutsch: „aufgabeln“) der Repository deiner Wahl
  2. Klone es auf deinen lokalen PC
  3. Erstelle einen neuen Branch
  4. Mache die gewünschten Änderungen
  5. Teste, ob alles funktioniert
  6. Committe die Änderungen
  7. Synchronisiere alles mit GitHub
  8. Schlage die Änderungen in einem Pull-Request in einem unserer Repositories vor
  9. Ändere deinen PR wenn nötig
  10. Dein PR wird von den Mitarbeitern in den Master-Branch eingefügt

Einzelheiten bitte!

1. Forking a Repo

Bemerkung

Dieser Schritt wird nur benötigt, wenn Sie keine Push-Rechte an dem Repository haben, an dem sie arbeiten. Wenn Sie an Ihrem eigenen Repository arbeiten, wird kein Fork benötigt. Dann können Sie diesen Schritt einfach überspringen und direkt klonen. Wenn Sie Änderungen an Sponge vornehmen und nicht kein Mitarbeiter sind, ist dieser Schritt notwendig.

Jetzt, da Sie das grundlegene Konzept kennen, werden wir die Details besprechen. Als erstes müssen Sie das Repository forken, an dem Sie Änderungen vornehmen wollen. Dies kann man auf GitHub.com machen, wo Sie einen Fork-Button am Anfang der Repository-Seite finden werden. Nachdem Sie ihn gedrückt haben, wird GitHub ein bisschen Arbeit verrichten und ihnen ein Duplikat des Originalrepositorys präsentieren. Sie werden feststellen, dass sich das Duplikat jetzt unter ÌhrGitHubAccount/NameDesGeklontenRepository` befindet. Gut, erster Schritt abgeschlossen.

Bemerkung

Alle Branches des originalen Repositories werden auch geforkt, Sie werden ein genaues Abbild, des geforkten Repos bekommen.

Repo forking

2. Cloning the Fork to Your local Machine

Now you need to get this fork to your local machine to make your changes. Open the Git Client of your choice (Git installieren) and clone your fork to your local machine. The client will ask you for a folder to store everything in. Second step finished, well done!

Bemerkung

Die meisten Schritte können per GUI erledigt werden. Wenn Sie erfahren mit der Kommandozeile sind, können Sie auch diese nutzen. Jeder Schritt wird Ihnen die benötigten Kommandos zeigen, um das gewünschte Ergebnis zu erreichen.

Alternativ können Sie das über CLI (command line interface, CMD oder powershell auf Windows) machen. Beachten Sie aber, dass Sie zuerst einen Ordner erstellen müssen, in den alles für Sie geklont wird, bevor Sie folgendes Kommando eingeben:

git clone git://github.com/YourGitHubAccount/ClonedRepoName.git
Repo cloning

3. Creating a New Branch

Jetzt, da Sie einen lokalen Klon von ihrem Fork haben, ist es an der Zeit, einen Branch zu erstellen, um daran zu arbeiten. Die Branches wurden entworfen, um verschiedene Features oder Ergänzungen gleichzeitig entwickeln und testen zu können, ohne Probleme und Fehler aufgrund von Interferenzen der Zusätze zu verursachen. Es ist streng empfohlen, Änderungen nicht direkt in den master-Branch zu machen. Stattdessen erstellen Sie selbst einen neuen Branch (mit einem sinnvollen Namen) und nehmen Sie dort die Änderungen vor.

Das impliziert, dass wir zuerst einen branch erstellen müssen, als los gehts! Sie können das über ihren Client machen (es sollte dort irgendwo einen create branch-Button geben), oder Sie benutzen das CLI mit Git:

git checkout -b [name_of_your_new_branch]

Dies wird einen branch mit einem Namen ihrer Wahl erstellen und auf ihn wechseln. Alle Änderungen die Sie jetzt vornehmen, werden auf diesem Branch gespeichert werden. Wenn Sie auf einen anderen Branch wechseln wollen (z.Bsp: master), verwenden sie einfach diesen Befehl. Dritter Schritt abgeschlossen! Gut Arbeit bis hierher! Um sich einen Überblick über die Branches zu verschaffen, benutzen Sie einfach Ihren Git-Client, oder:

git branch
Branches

Jetzt ist es an der zeit, Änderungen vorzunehmen. Benutzen Sie den Editor oder die IDE Ihrer Wahl, um das zu tun.

4. Test if Your Changes Work

Für die SpongeAPI und die Implementierungen müssen sie gradle compileJava ausführen. Fahren Sie mit dem nächsten Schritt fort, wenn es ohne Fehler ausgeführt wird. Wenn nicht, machen Sie die angemessenen Korrigierungen und versuchen Sie es erneut.

Für SpongeDocs können Sie einfach ihr PR einreichen. Diese wird automatisch eingefügt und mögliche Fehler enthüllen. Eine andere Möglichkeit ist es, die Docs lokal zu erstellen. Schauen Sie sich die Readme.md in den Docs für weiterführende Anweisungen an.

5. Commit the Changes

Wenn Sie fertig sin, müssen Sie diese in ein einzelnes Package bündeln (ein Commit) und sie in den Branch bekommen. Wieder wird Ihnen Ihr Git-Client helfen. Fügen Sie dem Commit einen sinnvollen Namen hinzu und - wenn benötigt - eine kurze Beschreibung. Das kann folgenderweise über das CLI getan werden:

Sammeln Sie zuerst alle Dateien, die Sie in einen Commit tun möchten:

git add <file>
git add <folder>

Jetzt, da die Dateien zu Ihrer Liste der Änderungen hinzugefügt sind, die du in den Commit aufgenommen haben willst, tue nur

git commit

Dies wird ein Textfenster öffnen, wo du - falls gewünscht - eine Nachricht hinzufügen kannst. Schau auf das Bild unterhalb. Du wirst bemerken, dass deine Commits immer noch nur lokal gespeichert sind und sich nicht auf dem Fork auf GitHub befinden.

Bemerkung

Du kannst mehrere Commits in einem PR haben. Mach einfach weiter, ändere alles, was du brauchst, und commite die Änderungen. Du kannst alle Commits später in einen einzigen zusammenführen.

Der sechste Schritt ist getan. Fast fertig!

Committing

6. Sync to GitHub

Nun müssen wir die Änderungen auf deinen Fork auf GitHub hochladen. Alles, was du bisher gemacht hast, ist nur lokal gespeichert. Wie immer kannst du deinen Git-Client nutzen (Es gibt einen Button in deinem GUI) oder du kannst es über den CLI tun:

git push <remote> <branch>

In diesem Fall sollte es sein:

git push origin feature/YourFeature
Pushing commits

7. Propose the Changes in a PR to the SpongePowered Repo

Du kannst entweder auf deine Fork-Seite auf GitHub.com gehen (Am obereren Rand der Forks-Seite sollte ein Hinweis sein, um dich zu führen), oder du kannst deinen GitHub-Client benutzen, um einen Pull-Request zu erstellen. Auf dem offiziellen GitHub-Client für Windows kann dies in der oberen, rechten Ecke des Fensters getan werden.

PRs

8. Amend Your PR if Necessary

Wenn du Änderungen an deinem PR machen willst, dann mache einfach mehr Commits zu dem oben erstellten Branch. Weitere Commits werden automatisch zum PR hinzugefügt.

9. Your PR Gets Pulled

Das war’s. Jetzt sind wir fertig. Gute Arbeit!

Fortgeschrittenes Git

Mit Rebase vereinen

Nehmen wir einmal an, du hast deine Ergänzungen zu dem Repository beendet und tun wir mal so, als hättest du während der Fertigstellung 137 Commits gemacht. Deine Commit-Historie wird ziemlich unübersichtlich aussehen. Es wäre eine Schande, wenn alle in das Repository aufgenommen werden würden, nicht wahr? Zu viele triviale Commits bringen auch auch den Projektverlauf in Unordnung. Glücklicherweise bietet Git hier ein Tolles Tool, um dieses Problem zu beseitigen, ein sogenannter Rebase. Das Rebase-Tool nimmt alle 137 kleinen Commits und packt sie in einen großen. Genial, nicht wahr? Anstatt das Rad neu zu erfinden, werden wir dir nur einen Link zu einem kleinen und leicht zu verstehenden „Squashing“-Tutorial geben:

Gitready: Vereinung mit Rebase

Das ist, was es tut, schön visualisiert:

Squashing commits

Einen Remote einrichten

Für gewöhnlich ist das originale Repository der direkte Parent deines Forks und dieser wiederum der direkte Parent deines lokalen Klons. Aber das originale Repository ist nicht der direkte Parent deines Klons. Das ist erst einmal kein Problem, aber es hindert dich daran, deinen Klon auf die neuesten Änderungen am originalen Repository zu aktualisieren. Wenn du aber das originale Repository als Remote (lies: Parent) deines Klones einrichtest, ist es dir möglich, alle Änderungen, die an diesem Repository gemacht wurden, zu nehmen und auf deinen lokalen Klon anzuwenden. Sieh weiter unten, wie „Grabbing und Updating“ funktioniert.

Setting up a remote

Also gut. Dieser Schritt wird durch CLI durchgeführt, da den meisten GUIs diese (eher fortgeschrittene) Funktionalität fehlt:

git remote add upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git

Wenn du dir unsicher bist, ob das so funktioniert hat, wie beabsichtigt, oder wenn du prüfen möchtest, welcher Remotes aktuell festgelegt sind, kannst du das darüber überprüfen:

git remote -v

Die Aussage sollte folgendermaßen aussehen:

origin    https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch)
origin    https://github.com/YOUR_USERNAME/YOUR_FORK.git (push)
upstream  https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (fetch)
upstream  https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (push)

Bemerkung

Falls du die Warnung fatal: The current branch DeinBranchName has no upstream branch. siehst, dann ist der Branch möglicherweise nicht auf dem Online-Remote. Dies passiert meistens, wenn das das erste Mal ist, wenn du einen Commit auf einen neuen Branch pushst. Um den neuen Branch zu pushen und den Remote online zu stellen, benutze git push --set-upstream origin DeinBranchName.

Rebasing

Angenommen du hast ein paar Änderungen an den gewünschten Branch gemacht, aber in der Zwischenzeit hat jemand anderes das Repository geupdated. Das bedeutet, dass dein Fork und dein Klon veraltet sind. Das ist kein großes Problem, um aber Probleme zu vermeiden, wenn du deine Hinzufügungen später mergest, ist es dringend empfohlen, deine Änderungen gegen die aktuellsten Änderungen zu rebasen. Wenn du das Remote-Repository noch nicht erstellt hast, mach es, bevor du versuchst zu rebasen.

Ein erfolgreicher Rebase benötigt mehrereSchritte:

1. Fetch the Changes on the Remote Repo

Zuerst müssen die Änderungen auf das Remote-Repository geholt werden. Dies geschieht (wieder) über CLI:

git fetch upstream

Das wird alle Änderungen vom Remote upstream hinzufügen und sie in einen temporären upstream/master Branch stecken.

2. Merge Remote Changes locally

Nun müssen wir den lokalen master-Branch auswählen:

git checkout master

Danach werden wir die Änderungen, die in upstream/master enthalten sind in unseren lokalen master-Branch mergen:

git merge upstream/master

Okay, das haben wir bisher geschafft:

Rebasing 1

3. Rebase Local Branch against Updated Master

Als nächstes musst du den lokalen Branch, in dem du arbeitest gegen deinen lokalen master-Branch rebasen. Dafür musst du auf deinen bearbeiteten Branch wechsteln (hier: feature\yourfeature) und dann einen Rabse ausführen. Das passiert über:

git checkout feature/yourfeature
git rebase master

Das wird deinen Branch zurückspulen, die Commits vom Master-Branch hinzufügen und dann deine eigenen Änderungen wieder anwenden. Das Ergebnis sieht folgendermaßen aus:

Rebasing 2

4. Push Everything to your Fork

Die letzte Sache, die wir tun müssen, ist es, alles zum Fork zu pushen. Wenn nu schon ein PR erstellt hast, wird dieser automatisch aktualisiert werden:

git checkout master
git push -f
git checkout feature/yourfeature
git push -f
Rebasing 3

Du hast es geschafft, super! Gute Arbeit und vielen Dank fürs Rebase-Air fliegen!