6. Issues & Boards

HinweisÜberblick

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

Frage: Wie organisiere ich Aufgaben in GitLab?

Lernziele:

  • Ein Issue anlegen, zuweisen, mit einem Label versehen, kommentieren und schließen
  • Ein Board nutzen, um einen Überblick über Issues zu bekommen

Ein Issue anlegen

Wir haben im Projekt unserer Partner:in mitgeschrieben und finden, dass wir dafür als Mitwirkende genannt werden sollten. Das soll die Partner:in selbst erledigen. Also legen wir in ihrem Projekt ein Issue an.

Issues sind Aufgaben, Fragen, Ideen oder Fehlermeldungen, gesammelt pro Projekt (oder Gruppe). Standardmäßig darf jede:r mit Lesezugriff Issues anlegen. So können auch Leute Probleme melden, die selbst nichts ändern dürfen.

HinweisIssues und Work items

In aktuellen GitLab-Versionen sind Issues eine Art von „Work items“. Daneben gibt es zum Beispiel Tasks (Unteraufgaben) und Incidents. Je nach Version heißt der Menüpunkt „Issues“ oder „Work items“.

  1. Das Projekt der Partner:in öffnen.
  2. Links „Plan“ → „Issues“ (bzw. „Work items“) wählen.
  3. „New issue“ (bzw. „New item“ mit Typ Issue) klicken.

Ausfüllen:

  • Title: kurz und aussagekräftig, zum Beispiel „Mitwirkende aufführen“.

  • Description:

    Externe Mitwirkende sollten in der Dokumentation genannt werden,
zum Beispiel:

* in einem Abschnitt der `README.md`
* in einer eigenen Datei `CONTRIBUTORS.md`

  • Assignee: die Partner:in auswählen. Sie muss Mitglied des Projekts sein.

Dann „Create issue“ klicken.

HinweisCode in Markdown

Wer Text in Schreibmaschinenschrift innerhalb eines Satzes setzen will, umschließt ihn mit Backticks: `README.md` wird zu README.md.

Für einen ganzen Block schreibt man eine Zeile mit drei Backticks davor und eine danach:

```
Dieser Block steht in Schreibmaschinenschrift,
    die Einrückung bleibt erhalten.
```

Die Issue-Seite zeigt oben Titel und Beschreibung, darunter Aktivität und Kommentarfeld und rechts eine Seitenleiste mit weiteren Feldern.

Ein Label vergeben

Wir möchten sehen, wann die Partner:in mit der Arbeit beginnt. Dafür gibt es Labels. Labels gelten pro Projekt oder pro Gruppe, und Gruppen-Labels stehen auch in allen Projekten der Gruppe zur Verfügung.

  1. Rechts in der Seitenleiste bei „Labels“ auf „Edit“ klicken.
  2. Im Dialog „Assign labels“ auf „Create project label“ klicken.
  3. Einen Namen eingeben, zum Beispiel „WIP“ (work in progress, in Arbeit), eine Farbe wählen und „Create“ klicken. Das Label wird angelegt und gleich zugewiesen.
  4. Den Dialog über das „X“ oder einen Klick daneben schließen.

Farben helfen beim Gruppieren, zum Beispiel eine Farbe für Themen und eine für den Bearbeitungsstand. Alle Labels eines Projekts verwaltet man unter „Manage“ → „Labels“.

Kommentieren und auf Commits verweisen

Wir wollen im Kommentar auf unseren Beitrag verweisen. Schreibt man in GitLab die Kennung eines Commits, wird daraus automatisch ein Link.

  1. Links „Code“ → „Commits“ öffnen. Neben unserem Commit steht eine kurze Folge aus Ziffern und Buchstaben, der Anfang der Commit-Kennung (SHA). Daneben ist ein Kopier-Button, den klicken wir.

  2. Zurück zum Issue gehen und einen Kommentar schreiben, zum Beispiel:

    Bitte nenn mich als Mitwirkende:n, siehe Commit 4eac24cafbcebc4f0d528bd2e1246a4624265085.

  3. „Comment“ klicken. Die Kennung erscheint gekürzt als Link.

Ein Issue schließen

Issues sind entweder offen oder geschlossen. Schließen kann man ein Issue

  • über das Menü „More actions“ (⋮) oben rechts → „Close issue“,
  • über das Board (siehe unten),
  • oder automatisch über einen Merge Request (Episode 7).

Issues löscht man in der Regel nicht. Auch geschlossene sind nützlich, etwa um später nachzulesen, ob ein Thema schon besprochen wurde.

Warnung

Schließt das Issue „Mitwirkende aufführen“ jetzt nicht. Wir brauchen es in Episode 7.

Issue Boards

Boards zeigen die Issues eines Projekts als Spalten, ähnlich wie Karten an einer Pinnwand (Kanban).

  1. Links „Plan“ → „Issue boards“ öffnen.
  2. Standardmäßig gibt es die Listen „Open“ und „Closed“. Die beiden kann man nicht löschen.
  3. Auf „New list“ klicken, das Label „WIP“ wählen und „Add to board“ klicken.

Die neue Liste erscheint zwischen „Open“ und „Closed“. Eigene Listen lassen sich dazwischen beliebig anordnen.

  • Offene Issues mit dem Label einer eigenen Liste stehen in dieser Liste und (nach einem Neuladen) nicht mehr in „Open“.
  • Geschlossene Issues stehen immer nur in „Closed“.

Mit dem Board ändert man auch Labels: Zieht man ein Issue in eine andere Liste, wird das alte Label entfernt und das neue gesetzt. Zieht man es nach „Closed“, wird es geschlossen; zieht man es dort heraus, ist es wieder offen.

Eigentlich soll die Partner:in das Label „WIP“ selbst setzen, wenn sie anfängt. Wir ziehen das Issue deshalb zurück nach „Open“.

Auf der Issue-Seite zeigt die Aktivität jetzt genau, wer wann was gemacht hat: Zuweisung, Label gesetzt, Kommentar, Label entfernt.

TippÜbung: Issues und Board (10 min)
  1. Legt in eurem eigenen Projekt zwei weitere Issues an, zum Beispiel „Tagebucheintrag für Freitag schreiben“ und „README um Kontakt ergänzen“.
  2. Legt ein zweites Label an, zum Beispiel „Idee“, und eine passende Liste im Board.
  3. Verschiebt die Issues im Board zwischen den Listen und schließt eines davon, indem ihr es nach „Closed“ zieht.
  4. Öffnet das geschlossene Issue und schaut euch die Aktivität an.

Zusatz: Vorlagen für Issues

Dieser Abschnitt ist optional, zum Beispiel wenn am Ende des Tages noch Zeit ist.

Manche Issues legt man immer wieder an, zum Beispiel Fehlermeldungen, Anfragen oder bei uns Tagebucheinträge. Damit sie jedes Mal gleich aufgebaut sind, kann man Vorlagen (Description templates) anlegen. Wer ein neues Issue erstellt, wählt die Vorlage aus, und die Beschreibung ist schon vorausgefüllt.

Vorlagen sind normale Markdown-Dateien in einem bestimmten Ordner des Projekts:

  • Vorlagen für Issues: .gitlab/issue_templates/
  • Vorlagen für Merge Requests: .gitlab/merge_request_templates/

Der Dateiname ohne .md wird zum Namen der Vorlage. Die Vorlage muss im Standard-Branch liegen (bei uns main).

Eine Vorlage anlegen

  1. Im eigenen Projekt über der Dateiliste auf „+“ → „New file“ klicken.

  2. Als Dateinamen den ganzen Pfad eintragen: .gitlab/issue_templates/Tagebucheintrag.md. Die Ordner legt GitLab beim Speichern automatisch an. Der Punkt am Anfang von .gitlab gehört dazu.

  3. Inhalt eintragen:

    ## Datum

## Was soll in den Eintrag?

- [ ]
- [ ]

/label ~Idee

  4. „Commit changes“ klicken, eine Commit-Nachricht schreiben (z. B. „Issue-Vorlage für Tagebucheinträge“) und bestätigen.

Neu in der Vorlage ist die Zeile /label ~Idee. Sie ist eine Quick Action. Beim Anlegen des Issues setzt GitLab automatisch das Label „Idee“ und entfernt die Zeile aus der Beschreibung. Das Label muss im Projekt schon existieren (wir haben es in der Übung oben angelegt). /label muss ganz am Anfang der Zeile stehen, ohne Leerzeichen davor, sonst führt GitLab die Quick Action nicht aus.

Die Vorlage verwenden

  1. Ein neues Issue anlegen (wie oben).
  2. Über dem Beschreibungsfeld auf „Choose a template“ klicken und „Tagebucheintrag“ wählen.
  3. Die Platzhalter ausfüllen und das Issue erstellen.
TippÜbung: Eigene Vorlage (10 min)
  1. Legt in eurem eigenen Projekt die Vorlage Tagebucheintrag an.
  2. Erstellt damit ein neues Issue. Prüft, ob das Label „Idee“ gesetzt wurde.
  3. Überlegt: Welche Issues legt ihr in eurer Arbeit immer wieder an? Wie würde eine Vorlage dafür aussehen?

Kernaussagen

  • Issues haben Titel und Beschreibung und sind offen oder geschlossen.
  • Issues lassen sich Personen zuweisen und mit Labels versehen.
  • Boards geben einen Überblick über Issues und ihren Stand, und dort lässt sich der Stand auch ändern.
  • Mit Vorlagen in .gitlab/issue_templates/ sind wiederkehrende Issues einheitlich aufgebaut (optional).