Developing FreeCAD with GitKraken/de

Vorwort

FreeCAD verwendet Git zur Verwaltung des Quellcodes. Dieses Dokument ist eine oberflächliche Einführung in GitKraken, eine grafische Benutzeroberfläche von Git. GitKraken ist eine proprietäre Software, die für den nicht kommerziellen Gebrauch kostenlos ist; du brauchst GitKraken nicht, um Code für FreeCAD zu entwickeln, aber viele Entwickler mögen es und finden es nützlich, ihre Entwicklung zu verwalten. FreeCAD unterstützt GitKraken nicht, aber wir hoffen, dass ein Leitfaden wie dieser den Anwendern zeigt, wie einfach es ist, die Entwicklungsumgebung einzurichten, und ermutigt mehr Menschen, sich zu beteiligen.

Weitere Informationen zur allgemeinen Git Nutzung über die Befehlszeile findest Du unter Source code management und im Online Buch Pro Git. Zur Kompilierung von FreeCAD siehe Kompilieren.

Einleitung

Git ist ein leistungsfähiges Revisionskontrollsystem, das häufig verwendet wird, um die Entwicklung von Computercode zu verfolgen. Obwohl es sich um ein komplexes System handelt, benötigst Du in der Regel nur einige Hintergrundinformationen über die Funktionsweise und einige wenige Terminalbefehle. Eine grafische Benutzeroberfläche (GUI) erleichtert die Lernkurve. GitKraken ist ein proprietäres Programm, das für den nicht kommerziellen Gebrauch kostenlos ist und auf dem Gerüst Electron läuft, d.h. es ist plattformübergreifend und kann unter Linux, MacOS und Windows gleichermaßen verwendet werden.

Einrichten der Git Entwicklung

Es gibt unterschiedliche Wege zum Herunterladen von GitKraken, abhängig von Deinem Betriebssystem. In Linux Distributionen kann man es manchmal über den Paketmanager beziehen.

GitKraken Herunterladen.
Gehe in deinem Webbrowser zu: https://github.com/FreeCAD/FreeCAD.
Auf die Schaltfläche Fork klicken. Dadurch wird das Repository FreeCAD/FreeCAD in das eigene Konto geklont. Mit anderen Worten: Die URL für den Zugriff auf den Fork lautet:
```
https://github.com/GITHUBUSERNAME/FreeCAD.git
```
Öffne GitKraken, gehe zu Datei → Klone Repo, und gib diese Addresse ein.
GitKraken wird nun dein persönliches Repositorium git klonen. Bitte den Unterschied zwischen origin vs. upstream Remote-Repository lesen. Im Wesentlichen ist der Fork von FreeCAD das origin-Repository, während das offizielle FreeCAD-Repository upstream ist. Man muss nun den Upstream entsprechend einstellen.
Die Seitenleiste in Gitkraken suchen. Dort gibt es einen Abschnitt Lokal und einen Abschnitt Remote. Lokal bezieht sich auf die lokalen Branches. Remote bezieht sich auf Remote-Repositorys und deren Branches. Fügen wir das FreeCAD-Repo als Remote hinzu. Im Abschnitt Remote auf die Schaltfläche + (wie in der Abbildung unten gezeigt) klicken.
Ein Dialogfeld Add Remote wird geöffnet. Auf das Github-Symbol (1) klicken. Im Feld Github-Repo (2) nach FreeCAD/FreeCAD suchen und darauf klicken. Im Feld Name upstream eintippen. Dann auf die Schaltfläche Schaltfläche hinzufügen klicken.
Der Dialog wird geschlossen und man gelangt zurück zur Hauptschnittstelle von GitKraken. Diesmal den Abschnitt Lokal in der Seitenleiste suchen und auf den Zweig master doppelklicken, um zu diesem zu wechseln. In der Befehlszeile entspricht dies
```
git checkout master
```
Auf das Symbol Push oben rechts in der Benutzeroberfläche klicken. Dadurch wird der Lokale Master auf dem Remote-Origin-Master übertragen.

Die GitKraken Oberfläche

Für weitere Informationen konsultiere GitKraken Erste Schritte Leitfaden.

*Lokal* bezeichnet den lokalen Rechner
Lokaler Master	Die lokale Verzweigung des FreeCAD-Master-Zweigs, gekennzeichnet durch die blaue Linie in der Bildschirmaufnahme. The item is highlighted in green, meaning that the branch is currently active (`git checkout`).
Local <branch-name>	Any other branches on your local machine. In the screenshot you can see branches called `editor_fixes` and `editor_fixes_typos`

*Remote* indicates a remote repository, for example in GitHub
Remote upstream	The official FreeCAD repository `https://github.com/FreeCAD/FreeCAD`, indicated by the green line in the screenshot.
Remote origin	Your personal fork of FreeCAD, `https://github.com/YourGitHubUsername/FreeCAD`, indicated by the red line in the screenshot.

GitKraken interface showing three local branches including a local master, and remote origin and upstream repositories, each of which have a master and release branches.

In the image, the remote the Local master and Remote origin master branches are three commits behind the Remote upstream master, that is, the official FreeCAD source code. This is indicated by the icons being three steps behind in the chain that represents the commit history of the master branch. See Rebasing to update the branches that are behind.

Rebasing

Checkout the Local master branch by double clicking on it (git checkout master)
Move the mouse to the last upstream commit, right click, and choose Rebase master onto upstream/master (git pull upstream master)
Now press the Push button (git push origin master). This pushes from your Local master to the Remote origin master.

Durch das Rebasing eines lokalen Masters wird dieser so aktualisiert, dass er mit dem Inhalt des Upstream-Masters übereinstimmt.

Zweige

Branches sind eine Funktion, die Git im Vergleich zu anderen Revisionssystemen so leistungsstark macht. Branches sind keine vollständigen Forks, sondern definieren Snapshots, bei denen eine Version des Codes vom Master-Branch abzweigt. Wenn Sie den FreeCAD-Code ändern möchten, erstellen Sie zunächst einen Branch, nehmen Sie dann die Änderungen vor und führen Sie anschließend Ihre Commits wieder mit dem Master-Branch zusammen. Mit Git ist es ganz einfach, Branches zu erstellen, zusammenzuführen und zu löschen, wenn Sie sie nicht mehr benötigen. Bitte lesen Sie Branching and Merging, um mehr über diesen Prozess in GitKraken zu erfahren.

Make sure you currently have the master branch active (double click on it, git checkout master). In GitKraken the Local master branch should be highlighted in green.
Click the Branch button to create a new branch and enter its new name (git checkout -b new-name-of-your-branch).

Pull Anfragen stellen

Pull-Anfragen (PRs) sind erforderlich, um den Code in einem Branch in Ihrem lokalen Repository mit dem Code im upstream-Repository zusammenzuführen. Zusammenfassend lässt sich sagen, dass man, nachdem man den Branch geändert habt, diesen zum GitHub-Fork (origin, https://github.com/GITHUBUSERNAME/FreeCAD.git) pushen und von dort aus einen Pull-Request an upstream stellen muss. GitKraken erspart einige Klicks, da man Pull-Requests ganz einfach erstellen kann, anstatt die GitHub-Oberfläche zu verwenden.

Steps in GitKraken:

Find you local branch on the interface and make sure it's active (double click on it).
Right click the branch name and find the option to Push <your-branch-name> and start a pull request.

GitKraken will open a dialog that asks you to confirm the repository which your branch will use to pull and push. It will then push your local branch to that remote repository.

GitKraken fragt, wie man den Remote-Branch benennen möchte. Der Standardname entspricht dem Namen, den der Branch lokal auf dem Computer hat.

GitKraken then opens up another dialog asking the repositories and branches to merge, and the direction (from and to).

You normally want to merge from the remote origin <your-branch-name> (GITHUBUSERNAME/FreeCAD) to the remote upstream master branch (FreeCAD/FreeCAD). Be sure to enter a good title for the pull request, and write a more descriptive paragraph if your changes are significant. Consult the official documentation of GitKraken for more information.

Auflösen von Zusammenführungskonflikten

GitKraken verfügt über ein spezielles Werkzeug für Merge-Konflikte, das nur in der GitKraken Pro-Version verfügbar ist. Es gibt jedoch Workarounds, um externe Werkzeuge für das Mergen zu verwenden.

GitKraken-kompatible externe Merge-Tools: Beyond Compare, FileMerge, Kaleidoscope, KDiff, Araxis, P4Merge
Wenn keine der oben genannten Optionen funktioniert, kann man externe Merge- und Diff-Tools in der Konfigurationsdatei ~/.gitconfig im Benutzerverzeichnis angeben.

Squashing commits

Als Versionskontrollsystem empfiehlt Git, viele Commits durchzuführen, um die Änderungen zu verfolgen. Wenn man jedoch zu viele kleine Änderungen vornimmt, kann die Commit-Historie etwas unübersichtlich werden. Squashing bedeutet, mehrere Commits zu einem einzigen Commit zusammenzufassen. Laut dem GitKraken-Handbuch ist Squashing für Commits verfügbar, die die folgenden Anforderungen erfüllen:

Man muss mindestens zwei Commits auswählen, um sie zu squashen.
Der jüngste Commit, gemessen am Commit-Datum, ist auch der aktuelle HEAD-Commit.
Genealogisch aufeinanderfolgend.
Chronologisch aufeinanderfolgend.
Der älteste Commit in der Liste hat einen Eltern-Commit.

Wenn alle diese Bedingungen erfüllt sind, wird die Option Squash angezeigt, wenn man mit der rechten Maustaste auf den Commit-Knoten klickt. Siehe Squash.gif

Anderen FreeCAD Repositorien folgen

You can use GitKraken to follow the personal FreeCAD forks of other developers; in this way you can see how they write code and commit changes to their own branches before they submit pull requests to the upstream FreeCAD/FreeCAD repository.

In the left side panel next to the Remote category, press the + sign.
A dialogue will come up to enter the name of the repository that you want to add. Recommended remotes are from the main FreeCAD developers and known contributors: wmayer, yorikvanhavre, ickby, sliptonic, kkremitzki, etc.
Press Add Remote.

Wenn nun neue Commits vorgenommen oder Branches von den Autoren dieser Repositorys rebasiert werden, wird deren Commit-Verlauf grafisch dargestellt.