**Mergen** und Diskutieren: Beiträge zusammenführen ######################################################################## .. index:: single: Merge Request single: Zusammenführungsanforderung ************************************************************************ *Merge Requests:* Beiträge diskutieren, annehmen und integrieren ************************************************************************ Eine *Zusammenführungsanforderung* (:dfn:`Merge Request`) ist die Basis zum Diskutieren, Annehmen und Zusammenführen von Beiträgen. Es ist genau so, wie der Name schon sagt: eine Aufforderung, einen Zweig in einen anderen zusammenzuführen. .. index:: single: Feature-Branch; Merge Request single: Quellzweig single: Zielzweig Hintergrund ======================================================================== Ein Repository besteht aus seinem Standardzweig (Standard-Branch) namens ``master``, der die Hauptversion des Inhalts enthält. Aus diesem werden Verzweigungen, *themenbezogene Feature-Branches*, erstellt, um Änderungen am Inhalt vorzuschlagen, ohne diese direkt in die Hauptversion einzuführen. Die Verzweigung ist besonders wichtig um zu vermeiden, dass Änderungen ohne vorherige *Überprüfungen, Tests und Genehmigungen* direkt in die Hauptversion übertragen werden. Wenn Sie einen neuen Feature-Zweig erstellen und bearbeiten, haben Sie die Möglichkeit, eine *Merge Request* zu erstellen. Dies ist im Wesentlichen eine Anforderung, einen Branch in einen anderen zusammenzuführen. Der Zweig, in den Sie Ihre Änderungen eingefügt haben, wird als **Quellzweig** bezeichnet, während der Zweig, in dem Sie Ihre Änderungen zusammenführen möchten, als **Zielzweig** bezeichnet wird. Der Zielzweig kann der Standard-Zweig ``master``, oder auch ein beliebiger anderer Zweig (z. B. der Zweig eines Abschnittredakteurs, der die Änderung zuerst begutachten soll) sein, je nach gewünschtem Ergebnis. Bei einem Merge Request können Sie nicht nur die Unterschiede zwischen dem ursprünglichen Inhalt und Ihren vorgeschlagenen Änderungen visualisieren, sondern auch eine erhebliche Anzahl von Aufgaben ausführen, bevor Sie Ihre Arbeit abschließen und die Zusammenführungsanforderung zusammengeführt wird. Ein Merge Request ist immer auch als **Diskussionsgrundlage** zu verstehen. Wenn Sie eine neue Zusammenführungsanforderung starten, können Sie die folgenden Optionen sofort einschließen oder später hinzufügen, indem Sie auf der Seite der Zusammenführungsanforderung oben rechts auf die Schaltfläche Bearbeiten klicken: - An einen berechtigten Mitarbeiter zuweisen - Meilenstein definieren, um zeitkritische Änderungen zu verfolgen. - Aktivieren Sie die Option :guilabel:`Quellzweig löschen`, wenn Zusammenführungsanforderung akzeptiert wird, um Ihr Repository sauber zu halten. Löschen Sie Feature-Zweige beim Zusammenführen oder nach dem Zusammenführen, um Ihr Repository sauber zu halten. - Legen Sie die Zusammenführungsanforderung als WIP (Work In Progress) fest, um versehentliche Zusammenführungen zu vermeiden, bevor sie bereit sind. - Besprechen Sie Ihre Implementierung mit Ihrem Team in der Merge-Request-Diskussion .. index:: single: Merge Request; erstellen single: Web-IDE; Merge Request erstellen Erstellen eines Merge Requests: *"Bitte übernimm' meinen Beitrag"* ======================================================================== Es gibt zwei wichtige Stellen an denen ein Merge Request gestartet werden kann: - In der WebIDE beim Speichern/Comitten eines Beitrags - In der Branch-Übersicht .. figure:: /Bilder/GitLab/GitLab-Project-WebIde-Aenderung-Commit.png :width: 100% Starten eines Merge Request beim Committen in der WebIDE Mittels der Checkbox :guilabel:`Start a new merge request` kann gleichzeitig mit dem Commit auch eine Zusammenführungsanforderung (Merge Request) gestartet werden. .. figure:: /Bilder/Screenshots/Gitlab/MergeRequest-BranchesOverview.png :width: 100% Starten eines Merge Requests von der Branches-Übersicht Unter :menuselection:`Repository --> Branches` können alle Branches eines Repository angezeigt werden. Mittels des Buttons :guilabel:`Merge-Request` kann ein Merge Request gestartet werden. Das Fenster *"New Merge Request"* ------------------------------------------------------------------------ Zusammenführungsanforderungen (auch als "MRs" bezeichnet) enthalten zahlreiche Informationen zu den vorgeschlagenen Änderungen. Der Hauptteil eines MR enthält seine Beschreibung sowie sein Widget (das Informationen zu CI / CD-Pipelines anzeigt, sofern vorhanden), gefolgt von den Diskussionsthreads der Personen, die mit diesem MR zusammenarbeiten. MRs enthalten auch Navigationsregisterkarten, auf denen Sie die Diskussion im Thread, die Liste der Commits, die Liste der Pipelines und Jobs, die Codeänderungen und Inline-Codeüberprüfungen sehen können. .. figure:: /Bilder/Screenshots/Gitlab/NewMergeRequest.png :width: 100% Ein neuer **Merge Request** Merge Requests enthalten zahlreiche Informationen zu den vorgeschlagenen Änderungen. Der Hauptteil eines MR enthält seine Beschreibung, gefolgt von den Diskussionen der Personen, die mit diesem MR zusammenarbeiten. MRs enthalten auch Navigationsregisterkarten, auf denen Sie die Diskussion im Thread, die Liste der Commits und die Codeänderungen sehen können. Von wo wohin? Eingabe des Ziel-Branches ------------------------------------------------------------------------ Die Zusammenführungsanforderung zielt standardmäßig auf den ``master``-Zweig ab. Sollte dies nicht gewünscht sein, z. B. weil man die Änderungen erst in einen anderen Branch (z. B. den Branch eines Kapitelredakteurs) integrieren möchte, muss dies in der Kopfzeile mittels :guilabel:`Change branches` entsprechend geändert werden. .. figure:: /Bilder/Screenshots/Gitlab/MergeRequest-New-ChangeBranches-1.png :width: 100% Quell- und Zielzweig (from ... into ...) Die Zusammenführungsanforderung zielt standardmäßig auf den ``master``-Zweig ab. Dies kann mittels :guilabel:`Change branches` geändert werden .. figure:: /Bilder/Screenshots/Gitlab/MergeRequest-New-ChangeBranches-2.png :width: 100% Änderung des Ziel-Zweigs Der Ziel-Zweig ("Target branch") wurde von ``master`` ... .. figure:: /Bilder/Screenshots/Gitlab/MergeRequest-New-ChangeBranches-3.png :width: 100% Änderung des Ziel-Zweigs ... auf ``gabriel`` geändert. Mit :guilabel:`Compare branches and continue` gelangt man wieder auf die Übersichtsseite. Die Basisdaten ------------------------------------------------------------------------ Geben Sie auf der Seite *"New Merge Request"** zunächst den Titel und die Beschreibung für die Zusammenführungsanforderung ein. Die Beschreibung soll möglichst klar die Änderungen und Besonderheiten zusammenfassen um den Reviewer entsprechend zu unterstützen. .. figure:: /Bilder/Screenshots/Gitlab/MerqueRequest-TitleDescription.png :width: 100% Merge Request: Titel und Beschreibung Die Beschreibung soll möglichst klar die Änderungen und Besonderheiten zusammenfassen um den Reviewer entsprechend zu unterstützen. Weitere Optionen ------------------------------------------------------------------------ .. figure:: /Bilder/Screenshots/Gitlab/NewMergeRequest-Properies.png :scale: 100% :align: center Die Optionen des neuen Merge Requests. .. figure:: /Bilder/Screenshots/Gitlab/MergeRequest-Assignee.png :scale: 100% :align: center Mit der Option :guilabel:`Assignee` kann ein zuständiger *Empfänger* ausgewählt werden. .. figure:: /Bilder/Screenshots/Gitlab/NewMergeRequest-Labels.png :scale: 100% Die Option :guilabel:`Labels` erlaubt das hinzufügen von ... Labels. Mit :guilabel:`Submit merge-request` wird schließlich der Merge Request bestätigt und gestartet. Review und Diskussion eines Merge Requests ======================================================================== Ein Merge Request als Zusammenführungsanforderung ist immer als **Diskussionsgrundlage** zu verstehen. Dementsprechend sind die Möglichkeiten für Review und Diskussion von Merge Requests besonders wertvoll. Diskussionen mittels Kommentarfunktion ------------------------------------------------------------------------ .. figure:: /Bilder/Screenshots/Gitlab/MergeRequest.png :width: 100% Merge Request: Kommentarfunktion Auf der Seite des Merge Requests können Kommentare hinterlassen werden, somit kann hier eine Diskussion über die Änderungen geführt werden. .. figure:: /Bilder/Screenshots/Gitlab/MergeRequest-MitKommentar.png :width: 100% Merge-Request-Seite mit Kommentar Anzeige und Review von Änderungen — Änderungsvergleiche ------------------------------------------------------------------------ .. figure:: /Bilder/Screenshots/Gitlab/MergeRequest-UebersichtCommitsAenderungen.png :scale: 100% :align: center Merge Request Auf der Seite des Merge Requests können die darin enthaltenen Commits und die kumulativen Änderungen angezeigt werden. .. figure:: /Bilder/Screenshots/Gitlab/MergeRequest-Aenderungen.png :width: 100% Anzeige der Änderungen, links alt, rechts neu. Hier wurden "nur" Zeilenumbrüche in der Datei ``Quelltext/Grundlagen/index.rst`` eingefügt. .. figure:: /Bilder/Screenshots/Gitlab/MergeRequest-Aenderungen-2.png :width: 100% Anzeige der Änderungen, links alt, rechts neu. Hier wurden "nur" Zeilenumbrüche in der Datei ``Quelltext/Grundlagen/index.rst`` eingefügt. Der Merge Request wird genehmigt ... ------------------------------------------------------------------------ Wenn der Merge Request genehmigt wird und der Feature-Branch in ``master`` integriert (gemerged) wird, wird in der Regel der Feature-Branch wieder gelöscht. Für weitere Änderungen soll ein neuer Feature- Branch erstellt werden. .. figure:: /Bilder/Screenshots/Gitlab/MergeRequest-Merged.png :width: 100% Der Merge Request wurde akzeptiert ... .. figure:: /Bilder/Screenshots/Gitlab/MergeRequest-Merged-Tree.png :width: 100% Diagramm der Abläufe in der Versionsverwaltung Mit Genehmigung des Merge Requests wurde die Änderung (grüner Feature-Zweig, links) in den ``master``-Zweig (rot, rechts) integriert, der Feature-Zweig ``Zeilenumbruch`` wurde bereits automatisch gelöscht.