7. Merge Requests

HinweisÜberblick

Dauer: ca. 30 min Input, 15 min Übungen

Frage: Wie schlage ich Änderungen an einem Projekt vor, in dem ich nichts ändern darf?

Lernziele:

  • Ein Projekt forken
  • Im Fork eine Datei anlegen
  • Einen Merge Request stellen und annehmen
  • Ein Issue automatisch über einen Merge Request schließen

Begleitfolien: Zusammenarbeiten in GitLab (PDF) – Folien 6–11: Fork, Branch, Merge Request, Review

Bisher haben wir direkt im Projekt der Partner:in gearbeitet und über Issues Wünsche geäußert. Jetzt lernen wir, konkrete Änderungen vorzuschlagen. Die Funktion dafür heißt Merge Request (MR), bei GitHub Pull Request. Wer die nötigen Rechte hat, prüft den Vorschlag und nimmt ihn an („merged“ ihn).

Wir legen eine Datei mit den Mitwirkenden an und lösen damit das Issue aus Episode 6.

HinweisBranch

Ein Branch ist eine parallele Arbeitsversion innerhalb eines Projekts. Die Hauptversion heißt meist main. Merge Requests führen einen Branch mit einem anderen zusammen. Wir arbeiten in dieser Episode in einem Fork direkt auf main. Innerhalb eines Projekts würde man stattdessen einen eigenen Branch anlegen.

Einen Fork anlegen

Als Mitglied könnten wir den Merge Request auch direkt im Projekt der Partner:in stellen. Bei fremden Projekten, in denen wir kein Mitglied sind, geht das aber nicht. Um auch das zu lernen, tun wir so, als hätten wir keine Schreibrechte.

Dann brauchen wir eine eigene Kopie, einen Fork. Der Name kommt von fork in the road, einer Weggabelung: Ab jetzt entwickeln sich zwei Versionen auseinander.

  1. Die Projektseite der Partner:in öffnen und oben rechts auf „Fork“ klicken. Die Zahl daneben zeigt, wie viele Forks es schon gibt.
  2. Das Formular ähnelt „Neues Projekt“, denn ein Fork ist ein neues Projekt:
    • Project name: Namen ändern, zum Beispiel „Forschungstagebuch Partnername“.
    • Project URL: euren Benutzernamen wählen.
    • Project slug: muss in eurem Bereich eindeutig sein, zum Beispiel forschungstagebuch-partnername.
    • Branches to include: egal, Standard ist „All branches“.
    • Visibility level: höchstens so offen wie das Original.
  3. „Fork project“ klicken.
WarnungNamen und Slug ändern!

Ihr habt schon ein eigenes Projekt „Forschungstagebuch“. Wenn Name oder Slug schon vergeben sind, scheitert der Fork, oft nur mit einer vagen Fehlermeldung. Dann die Seite neu laden und andere Werte wählen.

Der Fork ist ein vollwertiges Projekt. Kopiert wird aber nur das Repository, also die Dateien mit ihrer Historie. Issues zum Beispiel gibt es im Fork nicht.

Im Fork eine Datei anlegen

  1. Im Fork rechts über der Dateiliste „Edit“ → „Web IDE“ wählen.

  2. Über das Icon „Blatt mit Plus“ eine neue Datei CONTRIBUTORS.md anlegen.

  3. Inhalt:

    Folgende Personen haben am Forschungstagebuch mitgearbeitet:

- Vorname Nachname

  4. Committen (Source Control → Nachricht „CONTRIBUTORS.md hinzugefügt“ → auf main committen).

  5. Zurück zur Startseite des Forks gehen.

HinweisOhne Web IDE

Im Fork über der Dateiliste „+“ → „New file“, dann Dateiname, Inhalt und „Commit changes“ direkt auf main.

HinweisDateinamen in Großbuchstaben

Dateien mit Infos über das Projekt schreibt man traditionell groß: README, LICENSE, CONTRIBUTING, INSTALL, oft mit kleingeschriebener Endung.

Einen Merge Request stellen

  1. Im Fork links „Code“ → „Merge requests“ öffnen und „New merge request“ klicken.

  2. Source branch: euer Fork, Branch main.

  3. Target branch: das Originalprojekt der Partner:in (nicht euer Fork!), Branch main.

  4. „Compare branches and continue“ klicken.

  5. Titel und Beschreibung sind mit der Commit-Nachricht vorausgefüllt. In die Beschreibung schreibt ihr zusätzlich:

    Closes #<Nummer des Issues>

    Die Nummer steht beim Issue hinter dem Titel bzw. in der Adresse, zum Beispiel #1.

  6. „Create merge request“ klicken. Der Merge Request entsteht im Zielprojekt, also bei der Partner:in.

TippAbkürzung

Ist der Fork dem Original voraus, zeigt seine Startseite einen Kasten „Forked from …“ mit dem Button „Create merge request“. Er führt direkt zu Schritt 5.

HinweisIssues automatisch schließen

Wird ein Merge Request in den Standard-Branch übernommen und steht in seiner Beschreibung (oder in einer Commit-Nachricht) Schlüsselwort + Issue-Nummer, schließt GitLab das Issue automatisch.

Schlüsselwörter sind zum Beispiel Close/Closes/Closed, Fix/Fixes/Fixed, Resolve/Resolves/Resolved und Implement/Implements.

Die Seite des Merge Requests

Die Seite ähnelt einer Issue-Seite, hat aber Tabs:

  • Overview: Beschreibung, Diskussion, Status
  • Commits: alle Commits dieses Merge Requests
  • Pipelines: automatische Prüfungen (siehe Episode 8), die wir hier ignorieren
  • Changes: pro Datei ein Diff, also die Gegenüberstellung von Alt und Neu. Neue Zeilen sind grün mit +, entfernte rot mit -.

Im Tab Overview gibt es:

  • „Approve“: eine Freigabe. Sie ist standardmäßig optional, Projekte können sie aber verlangen.
  • „Merge“: bei euch ausgegraut, weil ihr (angeblich) keine Rechte im Zielprojekt habt. Die Partner:in kann mergen.
  • einen Hinweis, dass der Merge Request das Issue erwähnt.

Unten lässt sich der Merge Request kommentieren wie ein Issue. Im Tab Changes kann man außerdem einzelne Zeilen kommentieren: Mit der Maus über die Zeilennummer fahren, dann erscheint eine Sprechblase. So entstehen getrennte Diskussionen zu einzelnen Stellen.

HinweisReview

Dieses Vorgehen heißt Code Review: Jemand prüft Änderungen, bevor sie übernommen werden. Es funktioniert genauso für Texte, Metadaten oder Dokumentation.

Einen Merge Request annehmen

In der Zwischenzeit hat eure Partner:in dasselbe für euer Projekt gemacht.

  1. Das Issue in eurem Projekt öffnen. In der Aktivität steht „… mentioned in merge request !1“. „!1“ ist ein Link. Alternativ: links Code → Merge requests.
  2. Auf dieser MR-Seite ist „Merge“ aktiv. Darüber steht, was hinzugefügt wird: ein Commit und ein Merge-Commit.
  3. Optional einen Kommentar schreiben oder „Approve“ klicken.
  4. „Merge“ klicken. Kurz danach erscheint die Erfolgsmeldung.
  5. Das Issue über die Referenz (z. B. „#1“) öffnen. Es ist geschlossen, und die Aktivität zeigt, wodurch.

Der Merge-Commit führt die beiden Entwicklungsstränge, euer main und den des Forks, wieder zusammen.

TippÜbung: Review (10 min)
  1. Fügt im Fork eine weitere Zeile zu CONTRIBUTORS.md hinzu und committet sie. Öffnet den (schon gemergten oder noch offenen) Merge Request bzw. stellt einen neuen. Seht ihr den neuen Commit?
  2. Kommentiert im Tab Changes eine einzelne Zeile im Merge Request eurer Partner:in und antwortet auf ihren Kommentar.
TippGut zu wissen

Bearbeitet man in einem Projekt ohne Schreibrechte eine Datei („Edit“), bietet GitLab von selbst an, einen Fork anzulegen und einen Merge Request zu stellen. So geht ein kleiner Korrekturvorschlag in wenigen Klicks.

Kernaussagen

  • Ein Fork ist eine eigene Kopie eines Projekts.
  • Mit einem Merge Request schlägt man Änderungen vor, die andere prüfen und annehmen.
  • Mit Schlüsselwörtern wie Closes #1 schließt ein Merge Request Issues automatisch.