Die Projektzentrale GitLab™

Viele Arbeiten bzw. Abläufe am Projekt werden möglichst ortsunabhängig gestaltet, sodass die Mitarbeit auch von weit entfernten Teilnehmern problemlos und mit hoher Qualität ermöglicht wird. Analog zum Konzept des „Home Office“ liegt daher der Aufbau einer entsprechenden digitalen, Internet-basierten, Infrastruktur zur Zusammenarbeit (Kollaboration) nahe. Dies wird beim unserem Projekt durch die Plattform GitLab™ ermöglicht.

GitLab™ ist eine Web-basierte Plattform, welche einerseits einen bequemen Zugriff auf das Versionsverwaltungssystem Git ermöglicht, andererseits aber wesentliche Möglichkeiten für das Projektmanagement bietet (virtuelle Whiteboards, Ticket-System, Wiki, Diskussionsfunktionen, …). Außerdem erlaubt es die Bearbeitung von Textdateien direkt im Webbrowser, ohne dass sonst irgendwelche Software installiert werden muss.

Anmelden bei GitLab™

Für die Mitarbeit muss ein Mitarbeiter einen Benutzer auf GitLab™ erstellen und diesen dem Projektverantwortlichen bekannt geben um in das Projekt technisch aufgenommen zu werden und den Zugriff auf das Projektverzeichnis zu ermöglichen.

Die Webseite von GitLab™ lautet https://gitlab.com.

../../_images/GitLab-Home.png

Abb. 7 Home-Seite von GitLab™ nach dem Einloggen

Persönliche Einstellungen

Nachdem der Benutzer erstellt wurde kann die Sprache der Benutzeroberfläche auf Deutsch eingestellt werden (Icon in der Kopfleiste ganz rechts ‣ Settings ‣ Preferences).

../../_images/GitLab-Home-Einstellungen-2.png

Abb. 8 Einstellungen

„Commits“ sind Beiträge in einem „Repository“

Als Repository wird die Datenbank einer Versionsverwaltung bezeichnet, in welcher die gesamte Sammlung von Dateien und Ordnern, die einem Projekt zugeordnet sind, sowie deren Änderungsverlauf gespeichert ist. Der Versionsverlauf besteht aus einer baumartigen Kette von einzelnen Beiträgen, welche als Commit bezeichnet werden. Jedes Commit stellt eine Änderung dar, welche auf einer vorhergehenden Änderung aufbaut und von einem Beitragenden in das Repository eingetragen (committet) wurde. Gleichzeitig stellt jedes Commit einen Schnappschuss (engl.: Snapshot) dar, d. h. einen definiterten Versionsstand, der bei Bedarf jederzeit wiederhergestellt werden kann.

Jedes Commit hat eine eindeutige Prüfsumme bzw. ID („SHA-ID“). Diese ist eine kryptisch anmutende lange Zeichenkette, welche aus dem Inhalt des Commit berechnet wird. Mittels dieser Prüfsumme kann kann man ein Commit angebeben bzw. identifizieren. Da sie so lange ist, werden häufig nur die ersten Stellen angegeben, dies ist (meistens) ausreichend eindeutig.

../../_images/Commit-b531ee7a-2020-05-23.png

Abb. 9 Die ID (Prüfsumme) b531ee7a314f8ae3a15680a84a9da7ac2299e999 (oder kurz: b531ee7a) bezeichnet das Commit „Herzrhythmusstörungen überarbeitet“

../../_images/GitLab-Project-Repository-Commits.png

Abb. 10 Liste der Beiträge (Commits)

Zweige („Branches“) erlauben parallele Änderungen

Wie erwähnt besteht der Versionsverlauf aus einer aufeinander aufbauenden baumartigen Kette von Commits. Diese Kette kann sich aufzweigen wenn von einer Version unterschiedliche Änderungen eingetragen werden. Git erleichtert den Umgang und das Zusammenführen von parallelen Änderungen durch die Verwendung von Zweigen (engl. Zweig: Branch).

Während ein Autor in seinem Branch (Branch-Max) Änderungen vornimmt, kann ein anderer Autor ungestört in einem anderen Zweig (Branch-Moritz) seine Änderungen vornehmen. Zu einem beliebigen Zeitpunkt können dann die Änderungen integriert werden, dies wird als Merge bezeichnet (engl. to merge: verschmelzen). Wenn die Änderungen an unterschiedlichen Stellen passiert sind ist das in der Regel ein automatischer Vorgang. Lediglich wenn Änderungen nahe beieinander vorgenommen wurden, z. B. innerhalb der selben Zeile, muss der Konflikt (engl. merge conflict) manuell gelöst werden.

Der Hauptentwicklungszweig im Kompendium-Projekt heißt master und stellt die verbindliche Grundlage dar, hier werden schlussendlich alle angenommenen Beiträge von den Projektredakteuren eingepflegt. Umgekehrt bedeutet das, dass alle neuen Änderungen dem master-Branch entstammen (sollen).

../../_images/GitLab-Project-Repository-Branches.png

Abb. 11 Repository: Zweige (Branches)

../../_images/GitLab-Project-Repository-Diagramm.png

Abb. 12 Verlaufsbaum des Repositorys

Der Editor: „WebIDE“

Die WebIDE ist eine Anwendung, die direkt auf der Webseite von GitLab™ ausgeführt wird. Mit ihr können Dateien direkt auf der Webseite im Repository bearbeitet und als Beitrag (Commit) in einem Zweig (Branch) gespeichert werden.

Bearbeiten und speichern in der WebIDE

../../_images/GitLab-Project-WebIde.png

Abb. 13 Die WebIDE: Mit dem Editor im Browser können Dateien direkt auf der Webseite bearbeitet werden.

../../_images/GitLab-Project-WebIde-Aenderung.png

Abb. 14 Änderung: Ein neuer Satz

../../_images/GitLab-Project-WebIDe-Aenderung-Vormerken.png

Abb. 15 Die Änderung wird zur Eintragung vorgemerkt.

../../_images/GitLab-Project-WebIde-Aenderung-Vorgemerkt.png

Abb. 16 Die Änderung wurde zur Eintragung vorgemerkt.

../../_images/GitLab-Project-WebIde-Aenderung-Commit.png

Abb. 17 Die Änderung wird im Versionverwaltungssystem eingetragen („commitet“).

Mittels der Checkbox Start a new merge request kann gleichzeitig mit dem Commit auch eine Zusammenführungsanforderung (Megre Request) gestartet werden.

Kleines Vokabular

Branch

Zweig

Merge

Vereinigen/Integrieren von Branches

Merge Request

Antrag um einen Branch in einen anderen zu integrieren/vereinigen

Repository

Versionsverwaltungsdatenbank

Ticket

Ablauf: Eine Änderung

Wie bereits erwähnt besteht ein Repository aus verschiedenen Branches (Zweigen). Der Hauptentwicklungszweig heißt master und stellt die verbindliche Grundlage dar, hier werden schlussendlich alle Beiträge eingepflegt. Umgekehrt bedeutet das, dass alle neuen Änderungen dem master-Branch entstammen (sollen).

Was geschieht nun wenn ein Autor eine Änderung bzw. Änderung einpflegen möchte? Er startet die WebIDE im master-Zweig, öffnet die notwendigen Dateien und führt die Änderungen durch. Da der master-Branch schreibgeschützt ist kann er die Änderungen nicht direkt dort hinein committen, sondern er wird aufgefordert einen neuen Branch, als Kopie von master, zu erstellen. Dieser neue Branch wird Feature-Branch genannt, d. h. er ist eigentlich nur für dieses neue „Feature“ (= die Änderung bzw. Bearbeitung) vorgesehen. Dieser Feature-Branch kann verwendet werden um alle thematisch verwandten Änderungen vorzunehmen, der Hauptentwicklungszweig master wird dadurch nicht beeinträchtigt.

../../_images/ProjectOverview-2020-05-23-WebIDE.png

Abb. 18 Mittels Klick auf den Web IDE-Button in der Dateiansicht wird das WebIDE gestartet. Achtung: Der gewünscht Zweig muss vorher gewählt werden.

../../_images/WebIDE-2020-05-23-18-39-17.png

Abb. 19 Die WebIDE.

Links findet sich die Auswahl des Branches und der Ordner-/Dateibaum.

../../_images/WebIDE-2020-05-23-18-40-43.png

Abb. 20 Die Datei Quelltext/Grundlagen/index.rst, geöffnet in der WebIDE

../../_images/WebIDE-2020-05-23-18-41-51.png

Abb. 21 Die Datei Quelltext/Grundlagen/index.rst wurde geändert, links unten erscheint ein Commit…-Button …

../../_images/WebIDE-Commit-Button.png

Abb. 22 Durch Klick auf den Commit…-Button erscheint eine Eingabeaufforderung

../../_images/WebIDE-Commit.png

Abb. 23 Commit-Eingabe

Hier wird ein klingender Titel für den Beitrag vergeben. Da ein Mitarbeiter natürlich nicht Änderungen direkt in den master-Branch eintragen/speichern kann, muss ein neuer Branch erstellt werden, z. B. ein kurzlebiger Feature-Zweig. Hier wird er simpel Zeilenumbruch genannt. Wenn die Arbeiten abgeschlossen sind kann mittels der Option Start a new merge request ein neuer Merge Request gestartet werden.

Durch Klick auf den Commit Button wird die Änderung als Commit gespeichert und in das Versionsverwaltungssystem eingetragen

Eine Besonderheit muss bedacht werden: Wenn ein Branch einmal vom Hauptentwicklungszweig master abzweigt, so werden Änderungen, die in master einfließen, nicht automatisch in den Feature Branch übernommen! Der Feature-Zweig „lebt“ quasi parallel und autonom zum master. Da Feature-Branches in der Regel kurzlebig sind bzw. sein sollten spielt das selten eine Rolle, sollte es dennoch in speziellen Fällen notwendig sein, so kann ein Administrator den Feature Branch mit dem master abgleichen.1

1

Grundsätzlich kann jeder Autor den master-Branch (oder auch jeden anderen Branch) in „seinen“ Feature-Branch integrieren (mergen). Dazu wird ein Merge Request vom Quell-Branch mit dem Feature-Branch als Zielzweig erstellt und vom Autor selber bestätigt. Da dieser Weg relativ unintuitiv ist, und ausserdem Konflikte auftreten können (Änderungen an gleicher Stelle), ist es ratsam, sich im Zweifel der Hilfe eines Administrators zu bedienen.

Wenn die Bearbeitung abgeschlossen ist muss der Feature-Branch wieder in Hauptentwicklungszweig master integriert werden. Dies geschieht mit Hilfe eines sogenannten Merge Request. Der Merge Request ist im Prinzip als eine Art „Antrag“ zu verstehen, einen Branch in einen anderen zu integrieren. Dieser Request muss von einem Redakteur (Maintainer) bestätigt werden. Bevor dieser Merge Request bestätigt wird können noch Änderungen vorgenommen oder Diskussionen geführt werden. Das bedeutet, dass ein Merge Request eine Art Diskussionsplattform darstellt, wo Änderungen diskutiert werden können, dies stellt die erste Ebene der Qualitätssicherung dar.

../../_images/MergeRequest-2020-05-23-18-46-23.png

Abb. 24 Ein Merge Request wird erstellt

digraph { "0" [ shape = oval, color=black, style=filled, fillcolor=grey, fontcolor=black, fontname="Source Sans Pro", label="WebIDE von\nmaster öffnen", ]; "a" [ shape = note, color=black, style=filled, fillcolor=lightblue, fontcolor=black, fontname="Source Sans Pro", label="Änderungen durchführen", ]; "1" [ shape = tab, color=black, style=filled, fillcolor=orange, fontcolor=black, fontname="Source Sans Pro", label="Commit,\nFeature Branch erstellen", ]; "2" [ shape = note, color=black, style=filled, fillcolor=lightblue, fontcolor=black, fontname="Source Sans Pro", label="Weitere\nÄnderungen\ndurchführen", ]; "3" [ shape = invhouse, color=black, style=filled, fillcolor=orange, fontcolor=black, fontname="Source Sans Pro", label="Merge Request", ]; "4" [ shape = note, color=black, style=filled, fillcolor=lightblue, fontcolor=black, fontname="Source Sans Pro", label="Diskussion,\nÄnderungen", ]; "5" [ shape = cylinder, color=black, style=filled, fillcolor=palegreen, fontcolor=black, fontname="Source Sans Pro", label="Merge:\nFeature Branch\nin master", ]; "6" [ shape = box, color=black, style=filled, fillcolor=crimson, fontcolor=black, fontname="Source Sans Pro", label="Feature Branch löschen", ]; "0b" [ shape = oval, color=grey, style=filled, fillcolor=grey, fontcolor=black, fontname="Source Sans Pro", label="WebIDE von\nFeature-Branch öffnen", ]; 0 -> a -> 1 -> 2-> 3 -> 4 -> 5 -> 6 ; "0b" -> 2 [style=dashed, color=grey]; 2 -> 2 [label = " mehrfach",]; 4 -> 4 [label = " mehrfach",]; }

Abb. 25 Ablauf einer Bearbeitung

../../_images/WebIDE-2020-05-23.png

Abb. 26 Text


Achtung

Dieses Dokument ist in Entwicklung!

1.0.0-Release