.. index:: single: GitLab .. _Thema-Gitlab: **GitLab™**: Die Projektzentrale ######################################################################## 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 :program:`GitLab™` ermöglicht. :program:`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 `_. .. figure:: /Bilder/GitLab/GitLab-Home.png :width: 99.99% 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 (:menuselection:`Icon in der Kopfleiste ganz rechts --> Settings --> Preferences`). .. figure:: /Bilder/GitLab/GitLab-Home-Einstellungen-2.png :width: 99.99% 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. .. figure:: /Bilder/Screenshots/Gitlab/Commit-b531ee7a-2020-05-23.png :width: 100% Die ID (Prüfsumme) b531ee7a314f8ae3a15680a84a9da7ac2299e999 (oder kurz: b531ee7a) bezeichnet das Commit "Herzrhythmusstörungen überarbeitet" .. figure:: /Bilder/GitLab/GitLab-Project-Repository-Commits.png :width: 99.99% 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 auf\ *zweigen* 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 :dfn:`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). .. figure:: /Bilder/GitLab/GitLab-Project-Repository-Branches.png :width: 99.99% Repository: Zweige (Branches) .. figure:: /Bilder/GitLab/GitLab-Project-Repository-Diagramm.png :width: 99.99% 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 ============================================ .. figure:: /Bilder/GitLab/GitLab-Project-WebIde.png :width: 100% Die WebIDE: Mit dem Editor im Browser können Dateien direkt auf der Webseite bearbeitet werden. .. figure:: /Bilder/GitLab/GitLab-Project-WebIde-Aenderung.png :width: 100% Änderung: Ein neuer Satz .. figure:: /Bilder/GitLab/GitLab-Project-WebIDe-Aenderung-Vormerken.png :width: 100% Die Änderung wird zur Eintragung *vorgemerkt*. .. figure:: /Bilder/GitLab/GitLab-Project-WebIde-Aenderung-Vorgemerkt.png :width: 100% Die Änderung wurde zur Eintragung vorgemerkt. .. figure:: /Bilder/GitLab/GitLab-Project-WebIde-Aenderung-Commit.png :width: 100% Die Änderung wird im Versionverwaltungssystem eingetragen ("commitet"). Mittels der Checkbox :guilabel:`Start a new merge request` kann gleichzeitig mit dem Commit auch eine Zusammenführungsanforderung (Megre Request) gestartet werden. .. admonition:: 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 :dfn:`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. .. figure:: /Bilder/Screenshots/Gitlab/ProjectOverview-2020-05-23-WebIDE.png :width: 100% Mittels Klick auf den :guilabel:`Web IDE`-Button in der Dateiansicht wird das WebIDE gestartet. Achtung: Der gewünscht Zweig muss vorher gewählt werden. .. figure:: /Bilder/Screenshots/Gitlab/WebIDE-2020-05-23-18-39-17.png :width: 100% Die WebIDE. Links findet sich die Auswahl des Branches und der Ordner-/Dateibaum. .. figure:: /Bilder/Screenshots/Gitlab/WebIDE-2020-05-23-18-40-43.png :width: 100% Die Datei ``Quelltext/Grundlagen/index.rst``, geöffnet in der WebIDE .. figure:: /Bilder/Screenshots/Gitlab/WebIDE-2020-05-23-18-41-51.png :width: 100% Die Datei ``Quelltext/Grundlagen/index.rst`` wurde geändert, links unten erscheint ein :guilabel:`Commit...`-Button ... .. figure:: /Bilder/Screenshots/Gitlab/WebIDE-Commit-Button.png :scale: 100% :align: center Durch Klick auf den :guilabel:`Commit...`-Button erscheint eine Eingabeaufforderung .. figure:: /Bilder/Screenshots/Gitlab/WebIDE-Commit.png :scale: 100% :align: center 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 :menuselection:`Start a new merge request` ein neuer Merge Request gestartet werden. Durch Klick auf den :guilabel:`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.\ [#fn:FeatureBranchMaster]_ .. [#fn:FeatureBranchMaster] 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. .. figure:: /Bilder/Screenshots/Gitlab/MergeRequest-2020-05-23-18-46-23.png :width: 100% Ein Merge Request wird erstellt .. graphviz:: :caption: Ablauf einer Bearbeitung 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",]; } .. figure:: /Bilder/Screenshots/Gitlab/WebIDE-2020-05-23.png :width: 100% Text