Inhalt bearbeiten

Grundsätzliches und Struktur

Der Inhalt des Kompendiums liegt in Textdateien im Textformat restructuredText (ReST) vor. Diese befinden sich im Unterordner Quelltext und haben die Endung .rst.

Ein einfaches Beispiel wäre folgende Datei index.rst:

index.rst: Ein sehr simples ResT-Dokument

################################
Ich bin eine Überschrift
################################

Das ist der Text eines sehr kurzen und einfachen Dokuments.

Die Textdateien sind, angelehnt an die inhaltliche Gliederung, in einer Ordnerstruktur angeordnet. Die Hauptdatei einer jeden Gliederungsebene heißt index.rst.

Es ergibt sich somit folgende Struktur

graph {

"Projektordner"
        [
                shape=folder,
                color=black,
                style=filled,
                fillcolor=grey,
                fontcolor=black,
                fontname="Source Sans Pro",
                label="CCCA-Kompendium",
        ];
"Quelltext (/)"
        [
                shape=folder,
                color=mediumblue,
                style=filled,
                fillcolor=mediumblue,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="Quelltext (/)",
        ];

"/index.rst"
        [
                shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst"
        ];

"/Kapitel-1"
        [
                shape=folder,
                color=mediumblue,
                style=filled,
                fillcolor=mediumblue,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="Kapitel-1",
        ];
"/Kapitel-1/index.rst" [shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst"];
"/Kapitel-1/Thema-1"
        [
                shape=folder,
                color=mediumblue,
                style=filled,
                fillcolor=mediumblue,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="Thema-1",
        ];
"/Kapitel-1/Thema-1/index.rst" [shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst"];
"/Kapitel-1/Thema-2"
        [
                shape=folder,
                color=mediumblue,
                style=filled,
                fillcolor=mediumblue,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="Thema-2",
        ];
"/Kapitel-1/Thema-2/index.rst" [shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst"];




rankdir = TB;

subgraph {

        "Projektordner" -- "Quelltext (/)";
        "Quelltext (/)" -- "/index.rst"
                [color=coral];
        "Quelltext (/)" -- "/Kapitel-1"
                [color=mediumblue];
        "/Kapitel-1" -- "/Kapitel-1/index.rst"
                [color=coral];
        "/Kapitel-1" -- "/Kapitel-1/Thema-1"
                [color=mediumblue];
        "/Kapitel-1/Thema-1" -- "/Kapitel-1/Thema-1/index.rst"
                [color=coral];
        "/Kapitel-1" -- "/Kapitel-1/Thema-2"
                [color=mediumblue];
        "/Kapitel-1/Thema-2" -- "/Kapitel-1/Thema-2/index.rst"
                [color=coral];


        "/index.rst" -- "/Kapitel-1/index.rst" [style=dotted] ;
        "/Kapitel-1/index.rst" -- "/Kapitel-1/Thema-1/index.rst" [style=dotted] ;
        "/Kapitel-1/index.rst" -- "/Kapitel-1/Thema-2/index.rst"[style=dotted] ;

        {rank = same; "Quelltext (/)"; "/index.rst";}
        {rank = same; "/Kapitel-1"; "/Kapitel-1/index.rst";}



} /* closing subgraph */
}

Abb. 7 Projektordner und Unterordner: Im Unterordner befinden sich die Quelltextdateien, diese sind gemäß der inhaltlichen Gliederung in Unterordner aufgeteilt

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

Abb. 8 Projektverzeichnis in GitLab™

../../_images/Ordner-Quelltext-2020-05-23.png

Abb. 9 Der Quelltext-Ordner in GitLab™

../../_images/Ordner-Quelltext-2020-05-23.png

Abb. 10 Die Dateien und Ordner im Quelltext-Ordner

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

Abb. 11 Die Dateien und Ordner im obersten Ordner

Das Publikationsprojekt „Kompendium des CCCA“ hat einen eigenen Projektordner und mehrere Unterordner. Die wichtigsten Unterordner sind der Quelltext-Ordner und der Export-Ordner.

Im Quelltext-Ordner befinden sich eine oder mehrere Quelltext-Dateien mit dem eigentlichen Inhalt der Publikation. Quelltext-Dateien sind Roh- bzw. Klartext-Dateien, welche ausschließlich Zeichen beinhalten, ohne dirketen Formatierunginformationen oder anderen Objekten (Bilder usw.) – ähnlich einem mittels einer Schreibmaschine erstellten Dokument. Um Formatierungen, Bilder etc. zu ermöglichen und zu integrieren müssen die Quelltextdateien in einem bestimmten Format erstellt werden, dieses wird restructuredText, abgekürzt ResT oder RST, genannt. Diese Dateien werden von einem Programm, dem Compiler namens Sphinx, in ein gewünschtes Ausgabeformat (z. B. PDF für den Druck, HTML für Webseiten, ePub für eBooks, …) übersetzt.

digraph {

"Datei.rst"
        [
                shape = note,
                color=crimson,
                style=filled,
                fillcolor=white,
                fontcolor=crimson,
                fontname="Source Code Pro",
                label="Datei.rst",
        ];
"Compiler"
        [
                shape = box3d,
                color=grey,
                style=filled,
                fillcolor=black,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="Compiler\n(Sphinx)",
        ];



"Datei.pdf"
        [
                shape = note,
                color=black,
                style=filled,
                fillcolor=white,
                fontcolor=black,
                fontname="Source Serif Pro",
                label="Datei.pdf",
        ];

"Datei.html"
        [
                shape = note,
                color=blue,
                style=filled,
                fillcolor=white,
                fontcolor=blue,
                fontname="Source Sans Pro",
                label="Datei.html",
        ];
"Datei.epub"
        [
                shape = note,
                color=darkgreen,
                style=filled,
                fillcolor=white,
                fontcolor=darkgreen,
                fontname="Source Sans Pro",
                label="Datei.epub",
        ];

rankdir = TB;

subgraph {
        "Datei.rst" -> "Compiler" -> "Datei.pdf";
        "Compiler" -> "Datei.html";
        "Compiler" -> "Datei.epub";

        # {rank = same; "Datei.rst" ; "Compiler"}
        }
}

Abb. 12 Aus einer Quelltextdatei erzeugt der Compiler unterschiedliche Ausgabedateien und -formate

Die Quelltext-Dateien haben die Endung .rst. Ein einfaches Beispiel wäre folgende Datei index.rst:

index.rst

################################
Das ist ein Titel
################################

Das ist der Text eines Dokumentes

Gliederung

Ein Publikationsprojekt kann in mehrere Dateien aufgeteilt werden, sinnvollerweise geschieht dies anhand der Gliederungebenen (also z. B. der Kapitel oder unterabschnitte). Somit kann z. B. jedes Kapitel in einer eigenen Datei gespeichert werden. Es gibt dann eine Hauptdatei welche mittels der Direktive .. toctree:: Verweise auf andere Dateien enthält:

index.rst

################################
Das ist ein Titel
################################

.. toctree::

        Kapitel-1/index.rst

Dieser Text erscheint nach dem 1. Kapitel.

Der Compiler Sphinx fügt beim übersetzen an der entsprechenden Stelle die jeweilige(n) Datei(en) (hier Kapitel-1/index.rst, aber es könnte auch eine Kapitel-2/index.rst und eine Kapitel-3/index.rst geben) ein.

Eine Kapitel_Datei kann wiederum Verweise auf untergeordnete Abschnitte beinhalten:

Kapitel-1/index.rst

################################
Das ist Kapitel 1
################################

Dieses Kapitel ist das erste seiner Art.
Es werden im FOlgenden Thema 1 und Thema 2
behandelt.

.. toctree::

        Thema-1/index.rst
        Thema-2/index.rst

Es ergibt sich somit folgende Struktur

graph {

"Projektordner"
        [
                shape=folder,
                color=black,
                style=filled,
                fillcolor=grey,
                fontcolor=black,
                fontname="Source Sans Pro",
                label="Projektordner",
        ];
"Quelltext (/)"
        [
                shape=folder,
                color=mediumblue,
                style=filled,
                fillcolor=mediumblue,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="Quelltext (/)",
        ];

"/index.rst"
        [
                shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst"
        ];

"/Kapitel-1"
        [
                shape=folder,
                color=mediumblue,
                style=filled,
                fillcolor=mediumblue,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="Kapitel-1",
        ];
"/Kapitel-1/index.rst" [shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst"];
"/Kapitel-1/Thema-1"
        [
                shape=folder,
                color=mediumblue,
                style=filled,
                fillcolor=mediumblue,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="Thema-1",
        ];
"/Kapitel-1/Thema-1/index.rst" [shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst"];
"/Kapitel-1/Thema-2"
        [
                shape=folder,
                color=mediumblue,
                style=filled,
                fillcolor=mediumblue,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="Thema-2",
        ];
"/Kapitel-1/Thema-2/index.rst" [shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst"];




rankdir = TB;

subgraph {

        "Projektordner" -- "Quelltext (/)";
        "Quelltext (/)" -- "/index.rst"
                [color=coral];
        "Quelltext (/)" -- "/Kapitel-1"
                [color=mediumblue];
        "/Kapitel-1" -- "/Kapitel-1/index.rst"
                [color=coral];
        "/Kapitel-1" -- "/Kapitel-1/Thema-1"
                [color=mediumblue];
        "/Kapitel-1/Thema-1" -- "/Kapitel-1/Thema-1/index.rst"
                [color=coral];
        "/Kapitel-1" -- "/Kapitel-1/Thema-2"
                [color=mediumblue];
        "/Kapitel-1/Thema-2" -- "/Kapitel-1/Thema-2/index.rst"
                [color=coral];


        "/index.rst" -- "/Kapitel-1/index.rst" [style=dotted] ;
        "/Kapitel-1/index.rst" -- "/Kapitel-1/Thema-1/index.rst" [style=dotted] ;
        "/Kapitel-1/index.rst" -- "/Kapitel-1/Thema-2/index.rst"[style=dotted] ;

        {rank = same; "Quelltext (/)"; "/index.rst";}
        {rank = same; "/Kapitel-1"; "/Kapitel-1/index.rst";}



} /* closing subgraph */
}

Abb. 13 Quelltextordner

Wir sehen an dem Beispiel dass die Kapitel-Dateien immer index.rst heißen und in eigenen Ordnern liegen. Dies ist zwar nicht zwingend notwendig, es erleichtert jedoch die Arbeit mit den ausgegliederten Dateien und ist daher empfohlen. Dadurch kann die Dokumentenstruktur im Ordnerbaum eines Dateiverwaltungsprogramms (z. B. unter Windows™ dem Explorer oder unter MacOS™ dem Finder) einfach dargestellt werden.

../../_images/Ordnerstruktur-Basic.png

Abb. 14 Eine einfache Quelltext-Ordnerstruktur

../../_images/Ordnerstruktur-DieReisenDesMaxMustermann.png

Abb. 15 Eine etwas umfangreichere Quelltext-Ordnerstruktur

Der Quelltext-Ordner dieses Projekts schaut derzeit wie folgt aus (gekürzt):

Quelltext
├── _locales
├── _static
├── _templates
├── _themes
├── Bilder
│   └── Logos
│        ├── Ccca-Logo-10-AlmostEuColors-Variante-6-150px.png
│        ├── Ccca-Logo-10-AlmostEuColors-Variante-6-250px.png
│        ├── Ccca-Logo-10-AlmostEuColors-Variante-6-600px.png
│        └── Ccca-LogoBar-4-c-LongerBar.svg
├── Git
│   └── index.rst
├── GitLab
│   └── index.rst
├── Konventionen
│   └── index.rst
├── Organisation
│   └── index.rst
├── Projektordner
│   └── index.rst
├── Rst
│   └── index.rst
├── Sphinx
│   └── index.rst
├── UebersichtSpp
│   └── index.rst
├── conf.py
└── index.rst
graph {

"Projektordner"
        [
                shape=folder,
                color=black,
                style=filled,
                fillcolor=grey,
                fontcolor=black,
                fontname="Source Sans Pro",
                label="Projektordner",
        ];
"Quelltext (/)"
        [
                shape=folder,
                color=mediumblue,
                style=filled,
                fillcolor=mediumblue,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="Quelltext (/)",
        ];
"index.rst"
        [
                shape=note,
                color=crimson,
                fontcolor=crimson,
                fontname="Source Sans Pro",
                label="index.rst"
        ];
"/Bilder"
        [shape=folder, color=purple, fontcolor=purple fontname="Source Sans Pro", label="Bilder"];

"/Kapitel-1"
        [
                shape=folder,
                color=mediumblue,
                style=filled,
                fillcolor=mediumblue,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="Kapitel-1",
        ];
"/Kapitel-1/index.rst"
        [
                shape=note,
                color=crimson,
                fontcolor=crimson,
                fontname="Source Sans Pro",
                label="index.rst"
        ];
"/Kapitel-1/Thema-1"
        [
                shape=folder,
                color=mediumblue,
                style=filled,
                fillcolor=mediumblue,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="Thema-1",
        ];
"/Kapitel-1/Thema-1/index.rst"
        [
                shape=note,
                color=crimson,
                fontcolor=crimson,
                fontname="Source Sans Pro",
                label="index.rst"
        ];
"/Kapitel-1/Thema-2"
        [
                shape=folder,
                color=mediumblue,
                style=filled,
                fillcolor=mediumblue,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="Thema-2",
        ];
"/Kapitel-1/Thema-2/index.rst"
        [
                shape=note,
                color=crimson,
                fontcolor=crimson,
                fontname="Source Sans Pro",
                label="index.rst"
                ];
"/Kapitel-2"
        [
                shape=folder,
                color=mediumblue,
                style=filled,
                fillcolor=mediumblue,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="Kapitel-...",
        ];
"/Kapitel-2/index.rst"
        [
                shape=note,
                color=crimson,
                fontcolor=crimson,
                fontname="Source Sans Pro",
                label="index.rst"
        ];
"/Kapitel-3"
        [
                shape=folder,
                color=mediumblue,
                style=filled,
                fillcolor=mediumblue,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="Kapitel-...",
        ];
"/Kapitel-3/index.rst"
        [
                shape=note,
                color=crimson,
                fontcolor=crimson,
                fontname="Source Sans Pro",
                label="index.rst"
        ];

"Export"
        [
                shape=folder,
                color=forestgreen,
                style=filled,
                fillcolor=forestgreen,
                fontcolor=white,
                fontname="Source Sans Pro",
        ];
"Export/branch"
        [
                shape=folder,
                color=forestgreen,
                style=filled,
                fillcolor=forestgreen,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="branch"];
"Export/branch/html"
        [
                shape=folder,
                color=forestgreen,
                style=filled,
                fillcolor=forestgreen,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="html"
        ];
"Export/branch/epub"
        [
                shape=folder,
                color=forestgreen,
                style=filled,
                fillcolor=forestgreen,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="epub"
        ];
"Export/branch/latex"
        [
                shape=folder,
                color=forestgreen,
                style=filled,
                fillcolor=forestgreen,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="latex"
        ];

"Projektordner" -- "Quelltext (/)";
"Quelltext (/)" -- "index.rst" [color=mediumblue];
"Quelltext (/)" -- "/Bilder" [color=mediumblue];

"Quelltext (/)" -- "/Kapitel-1" [color=mediumblue];
"/Kapitel-1" -- "/Kapitel-1/index.rst"
        [color=crimson];
"/Kapitel-1" -- "/Kapitel-1/Thema-1" [color=mediumblue];
"/Kapitel-1/Thema-1" -- "/Kapitel-1/Thema-1/index.rst"
        [color=crimson];
"/Kapitel-1" -- "/Kapitel-1/Thema-2" [color=mediumblue];
"/Kapitel-1/Thema-2" -- "/Kapitel-1/Thema-2/index.rst"
        [color=crimson];

"Quelltext (/)" -- "/Kapitel-2" [color=mediumblue];
"/Kapitel-2" -- "/Kapitel-2/index.rst"
        [color=crimson];

"Quelltext (/)" -- "/Kapitel-3" [color=mediumblue];
"/Kapitel-3" -- "/Kapitel-3/index.rst"
        [color=crimson];

"Projektordner" -- "Export";

"Export" -- "Export/branch" [color=forestgreen];
"Export/branch" -- "Export/branch/html" [color=forestgreen];
"Export/branch" -- "Export/branch/epub" [color=forestgreen];
"Export/branch" -- "Export/branch/latex" [color=forestgreen];
}

Abb. 16 Die Ordnerstruktur

graph {

"Projektordner"
        [
                shape=folder,
                color=black,
                style=filled,
                fillcolor=grey,
                fontcolor=black,
                fontname="Source Sans Pro",
                label="Projektordner",
        ];
"Quelltext (/)"
        [
                shape=folder,
                color=mediumblue,
                style=filled,
                fillcolor=mediumblue,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="Quelltext (/)",
        ];
"Export"
        [
                shape=folder,
                color="#ccffcc",
                style=filled,
                fillcolor="#ccffcc",
                fontcolor=white,
                fontname="Source Sans Pro",
        ];
"/conf.py"
        [
                shape=note, color=grey, fontcolor=grey, fontname="Source Sans Pro", label="conf.py"
        ];
"/index.rst"
        [
                shape=note,
                color=crimson,
                fontcolor=crimson,
                fontname="Source Sans Pro",
                label="index.rst"
        ];

"/Kapitel-1"
        [
                shape=folder,
                color=mediumblue,
                style=filled,
                fillcolor=mediumblue,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="Kapitel-1",
        ];
"/Kapitel-1/index.rst"
        [
                shape=note,
                color=crimson,
                fontcolor=crimson,
                fontname="Source Sans Pro",
                label="index.rst"
        ];
"/Kapitel-1/Thema-1"
        [
                shape=folder,
                color=mediumblue,
                style=filled,
                fillcolor=mediumblue,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="Thema-1",
        ];
"/Kapitel-1/Thema-1/index.rst"
        [
                shape=note,
                color=crimson,
                fontcolor=crimson,
                fontname="Source Sans Pro",
                label="index.rst"
        ];
"/Kapitel-1/Thema-2"
        [
                shape=folder,
                color=mediumblue,
                style=filled,
                fillcolor=mediumblue,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="Thema-2",
        ];
"/Kapitel-1/Thema-2/index.rst"
        [
                shape=note,
                color=crimson,
                fontcolor=crimson,
                fontname="Source Sans Pro",
                label="index.rst"
                ];
"/Kapitel-2"
        [
                shape=folder,
                color=mediumblue,
                style=filled,
                fillcolor=mediumblue,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="Kapitel-...",
        ];
"/Kapitel-2/index.rst"
        [
                shape=note,
                color=crimson,
                fontcolor=crimson,
                fontname="Source Sans Pro",
                label="index.rst"
        ];
"/Bilder"
        [
                shape=folder,
                color=purple,
                style=filled,
                fillcolor=purple,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="Bilder",
        ];



"Projektordner" -- "Quelltext (/)";
"Projektordner" -- "Export"
        [
                color="#ccffcc";
        ];
"Quelltext (/)" -- "/index.rst"
        [color=crimson];
"Quelltext (/)" -- "/conf.py"
        [color=grey];
"Quelltext (/)" -- "/Bilder"
        [color=purple];

"Quelltext (/)" -- "/Kapitel-1"
        [color=mediumblue];
"/Kapitel-1" -- "/Kapitel-1/index.rst"
        [color=crimson];
"/Kapitel-1" -- "/Kapitel-1/Thema-1"
        [color=mediumblue];
"/Kapitel-1/Thema-1" -- "/Kapitel-1/Thema-1/index.rst"
        [color=crimson];
"/Kapitel-1" -- "/Kapitel-1/Thema-2"
        [color=mediumblue];
"/Kapitel-1/Thema-2" -- "/Kapitel-1/Thema-2/index.rst"
        [color=crimson];

"Quelltext (/)" -- "/Kapitel-2"
        [color=mediumblue];
"/Kapitel-2" -- "/Kapitel-2/index.rst"
        [color=crimson];


}

Abb. 17 Quelltextordner

Commits sind Beiträge in einem Repository

Ein Repository ist im Prinzip eine Datenbank, welche die gesamte Sammlung von Dateien und Ordnern, die einem Projekt zugeordnet sind, sowie deren Änderungsverlauf enthält. 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. 18 Die ID (Prüfsumme) b531ee7a314f8ae3a15680a84a9da7ac2299e999 (oder kurz: b531ee7a) bezeichnet das Commit „Herzrhythmusstörungen überarbeitet“

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

Abb. 19 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. 20 Repository: Zweige (Branches)

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

Abb. 21 Verlaufsbaum des Repositorys

Der Editor

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 gespeichert werden.

Schreiben, bearbeiten und speichern

Bearbeiten und speichern in der WebIDE

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

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

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

Abb. 23 Änderung: Ein neuer Satz

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

Abb. 24 Die Änderung wird zur Eintragung vorgemerkt.

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

Abb. 25 Die Änderung wurde zur Eintragung vorgemerkt.

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

Abb. 26 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. 27 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. 28 Die WebIDE.

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

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

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

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

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

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

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

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

Abb. 32 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. 33 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. 34 Ablauf einer Bearbeitung

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

Abb. 35 Text