Informatik/Mathematik / Software Engineering

Ziel: Organisation von Aufgaben und Prozessen im Team mit Hilfe von Issues und des OpenUP an einem gemeinsamen Repository auf GitHub

Praktikumsaufgaben Teil 4 - Zusammenarbeit 2

Die Bearbeitung der Aufgabe 1 und zum Teil in Aufgabe 2 erfolgt in Ihrem Team-Repository htwd-se-example-teamproject aus dem letzten Praktikum. In Aufgabe 3 nehmen Sie Ihr Repository htwd-se-example-project.

Hinweise zum Praktikum in den Windows-Laboren

Aufgrund der nicht gespeicherten Nutzer-Profile in den Windows-Laboren, sind zu jedem Praktikumsbeginn folgende Schritte durchzuführen:

Schritte zur Vorbereitung des Praktikums

  1. Git-Konfiguration C:\Users\<username>\.gitconfig wiederherstellen oder anpassen:

    per Editor in der .gitconfig
    [user]
	name = Vorname Nachname
	email = s00000@htw-dresden.de
[safe]
    directory = *
[http]
	proxy = http://www-cache.htw-dresden.de:3128
    oder per PowerShell und Git-Kommandos
    > git config --global user.name "Vorname Nachname"
> git config --global user.email s00000@informatik.htw-dresden.de
> git config --global --add safe.directory *
> git config --global http.proxy http://www-cache.htw-dresden.de:3128

  2. Visual Studio Code: Anpassen der AsciiDoc-Einstellungen:

    • Asciidoc > Preview: Use Editor Style: (deaktiviert)

    • Asciidoc > Extensions: Enable Kroki: (aktiviert)

  3. GitHub Login mit gespeichertem oder neuem Personal Access Token über die PowerShell bekanntgeben:

    Repository vorhanden
    > U:
> cd path/to/repository/<repo-name>/
> git pull
Authentifizierung ...
    Repository nicht vorhanden (Home-/SAMBA-Laufwerk)
    > U:
> cd path/to/repository/
> git clone https://github.com/.../<repo-name>
Authentifizierung ...
    Repository nicht vorhanden (TEMP-Laufwerk)
    > T:
> git clone https://github.com/.../<repo-name>
Authentifizierung ...

1. GitHub: Issues

Issues are a great way to keep track of tasks, enhancements, and bugs for your projects. They’re kind of like email—except they can be shared and discussed with the rest of your team. Most software projects have a bug tracker of some kind. GitHub’s tracker is called Issues, and has its own section in every repository. - GitHub

GitHub bietet mit dem Bereich Issues eine Möglichkeit anstehende Aufgaben, aufgetretene Probleme und mögliche Verbesserungen zentral in Ihrem Projekt innerhalb Ihres Repository zu verwalten und zu diskutieren.

Screenshot: Bereich Issues auf GitHub
Abbildung 1. Screenshot: Bereich Issues auf GitHub

Jeder Issue (Aufgabe, Ticket, …​) besteht aus einem Titel und der Beschreibung des Sachverhaltes. Zusätzlich können zur besserer Verwaltung noch Assignees (Beauftrage), Labels und weitere Kriterien hinzugefügt werden. Ebenfalls kann über Kommentar der Issue diskutiert und mit Anmerkungen versehen werden. Eine detailierte Beschreibung finden Sie in dem Guide: Mastering Issues

Bei Verwendung bestimmter Keywords (Closing issues using keywords) in den Commit Messages können referenzierte Issues automatisch geschlossen werden.

Hinweise: Verwenden von Referenzen in Issue-Kommentaren und Commits

In den Issues und Commits können in den Kommentaren/Mitteilungen Verweise auf andere Elemente verwendet werden. Diese werden von GitHub automatisch verlinkt.

Tabelle 1. Ausgewählte Verweise

Issue

Nummer

#2

Commit

SHA hash

5000fb638483c95d5f0346181af32096db2d23ff

User

Accountname

@account

Siehe auch: Autolinked references and URLs

Beispiele:

  • Commit Message:

    • Setze Erweiterung aus Issue #2 um

    • Setze Erweiterung um (#2)

  • Commit Message mit automatischem Schließen der zugehörigen Issue:

    • Korrigiere Fehler (close #2)

  • Issue Kommentar:

    • …​ siehe Commit 479bcfca71f10423c0f1181853017b83af062c46

Aufgabe 1.1 - Issues anlegen, kommentieren

Jeder im Team des Teamprojektes htwd-se-example-teamproject denkt sich eine kleine machbare Änderung oder Erweiterung für die Dokumentation in AsciiDoc aus.

Aufgabe - Person A, B, C

  1. Legen Sie jeweils zwei neue Issue in Ihrem Teamprojekt an. Denken Sie sich hierfür eine kleine, sinnvolle und umsetzbare Erweiterung für Ihre Dokumentation (AsciiDoc) im Projekt aus. Vergeben Sie einen Titel, eine Beschreibung und ein Label asciidoc.

  2. Schauen Sie sich die Issues Ihrer Teammitglieder an und diskutieren (kommentieren) Sie sie.

  3. Weißen Sie sich gegenseitig über Assignees je zwei Issue zu und ergänzen Sie ein Label documentation.

Aufgabe 1.2 - Issues bearbeiten, referenzieren

Aufgabe - Person A, B, C

  1. Setzen Sie Ihre erste zugewiesene Issue um und nehmen Sie in der Commit Message eine Referenz der zugehörigen Issue auf.

    Bspw. Commit Message mit Referenz zur Issue:
    Korrigiere falschen Teamnamen (Issue #6)

  2. Nehmen Sie in der Issue eine Referenz zu Ihrem Commit als Kommentar auf und schließen Sie die fertig bearbeitete Issue am Ende über GitHub.

    Bspw. Issue Kommentar auf GitHub mit Referenz zum Commit:
    Änderung der Teamnamen in Commit 5000fb638483c95d5f0346181af32096db2d23ff erfolgt.

  3. Setzen Sie Ihre zweite zugewiesene Issue um und nehmen Sie in der Commit Message eine Referenz mit Schlüsselwort zur automatischen Schließung der zugehörigen Issue auf.

    Bspw. Commit Message mit Referenz zur Issue und automatischer Schließung:
    Ändere Inhalt (close #6)

  4. Schauen Sie sich die Issues (Open & Closed) und die dazu entstandenen Kommentare und Verweise durch die Referenzen an.

Aufgabe 1.3 - Aufgabenlisten in Issues

In den Issue-Beschreibungen können auch Aufgabenlisten angelegt werden. Dies können Teilschritte einer Issue sein oder eine Art Check-Liste, ob bspw. alle genannten Teammitglieder diese erfüllt haben. Bei Bedarf können Teilaufgaben auch in neue Issues umgewandelt werden.

Siehe auch: Informationen zu Aufgabenlisten

Hinweise: Beispiele für Aufgabenlisten in Issues
Beispiel für Teilaufgaben:
Use-Case UC01 bearbeiten

- [ ] Kurzbeschreibung, Akteure und Vorbedingung erfassen
- [ ] Standardablauf ausarbeiten
- [ ] Szenario mit konkreten Daten zum Standardablauf ausarbeiten
- [ ] ...
Beispiel für eine Check-Liste:
Macht euch mit Aufgabenlisten vertraut.

- [ ] Person A
- [ ] Person B
- [ ] Person C
Aufgabe - Person A, B, C

  1. Erstellen Sie jeweils eine neue Issue und verwenden Sie in der Beschreibung eine Aufgabenliste.

  2. Wandeln Sie eine der Teilaufgaben in der Aufgabenliste in eine neue Issue um.

  3. Schauen Sie sich die eben erstellten Issues an.

2. Issues mit Filtern im Überblick behalten

In der Issues Anzeige von GitHub werden alle vorhandenen Issues und Pull Requests aufgelistet. Standardmäßig ist die Sicht mit is:issue is:open auf offene Issues gefiltert.

Issue-Ansicht in GitHub
Abbildung 2. Issue-Ansicht in GitHub
Hinweise zu den Filtermöglichkeiten

Für eine gezielte Sicht auf bestimmt Einträge, gibt es ein Vielzahl an Filtermöglichkeiten und deren Kombination. Ausgewählte finden Sie in der Tabelle 2, “Ausgewählte Filterkritterien” und eine komplette Liste und weitere Informationen unter folgenden Links:

Tabelle 2. Ausgewählte Filterkritterien
Filter Beschreibung

is:pr

Pull-Requests

is:issue

Issues

is:open

offen

is:closed

geschlossen

author:USERNAME

von einem Nutzer erstellt

assignee:USERNAME

einem Nutzer zugewiesen

label:LABEL

einem Label zugeordnet

milestone:MILESTONE

einem Meilenstein zugeordnet

project:PROJECT

einem Projekt zugeordnet
Tabelle 3. Filterkritterien für fehlende Angaben
Filter Beschreibung

no:label

keinem Label zugeordnet

no:milestone

keinem Meilenstein zugeordnet

no:project

keinem Projekt zugeordnet

no:assignee

keinem Nutzer zugeordnet

Ein Filter mit is:issue is:open no:assignee ist sehr hilfreich, um offenen Issues, welchen keine Nutzer zur Bearbeitung zugeordnet sind, im Blick zu haben. Über ein sort:created-asc lässt sich die Ausgabe zeitlich sortieren.

Filter lassen sich aktuell nicht direkt in GitHub speichern, aber die Seiten-URL enthält nach einer Suche den Filter und lässt sich so als Bookmark speichern. Für das obere Beispiel würde die URL am Ende wie folgt aussehen:
/issues?q=is:open+is:issue+no:assignee+sort:created-asc

Aufgabe 2.1 - Issues filtern

Listen Sie in Ihrem Team-/Projekt-Repository oder einem anderen Repository Issues nach folgenden Filtern auf:

  • Alle geschlossenen Issues und Pull-Requests seit Semesterbeginn

  • Alle Issues die keinem Nutzer (Assignee) zugeordnet sind

  • Alle offenen Issues die keinem Projekt oder Meilenstein zugeordnet sind

  • Alle Issues die Sie erstellt haben und einem bestimmten Label

  • Alle offenen Issues denen Sie zugeordnet sind

  • Alle Issues in denen das Wort "Meeting" vorkommt

  • Alle Issues und Pull-Requests mit mehr als 2 Kommentaren

Schauen Sie sich weiteren Filtermöglichkeiten über den Button Filters ▼ oder Schnellfilter im Listenkopf (Author, Label, Projects, Milestines, Asignees, Sort) an und denken Sie sich ein paar weitere nützliche Filtermöglichkeiten für Ihr Projekt aus.

3. Issues im Kontext des OpenUP

GitHub Issues im Kontext des OpenUP
Abbildung 3. GitHub Issues im Kontext des OpenUP

Mit Issues lassen sich in GitHub zu einem Repository Aufgaben (tasks), Verbesserungen (enhancements) und Fehler (bugs) verwalten (Siehe Issues). Projects helfen diese Issues zusätzlich zu organisieren, zu priorisieren und den Fortschritt im Blick zu halten.

OpenUP is a lean Unified Process that applies iterative and incremental approaches within a structured lifecycle. OpenUP embraces a pragmatic, agile philosophy that focuses on the collaborative nature of software development.
— Quelle: OpenUP

Folgend eine Variante der Abbildung des OpenUP mit den Möglichkeiten von Issues und Projects von GitHub (Siehe auch Abbildung 3, “GitHub Issues im Kontext des OpenUP”):

Tabelle 4. Abbildungsvariante OpenUP in GitHub
OpenUP GitHub Hinweise

Phase

Milestone

  • Inception Phase, Elaboration Phase, Construction Phase, Transition Phase

Iteration

Project

  • Einteilung der Work Items in Iteration [1..n]

  • extra Spalte (Field, iteration)

User Story

Issue

  • Kurze Beschreibung einer Anforderung

  • Noch kein konkretes Work Item

Work Item

Issue

  • Konkrete Aufgabe/Task

  • Wenn aus User Story entstanden, Verweis im Kommentar auf Issue-ID der zugehörigen User Story angeben

Work Item State

Issue

  • offen, geschlossen, Label

Project

  • Status (Table view) / Spalten (Board View): Todo, In Progress, Done, …​

Complexity

Project

  • extra Spalte (Field, numeric)

Note

Issue

  • Label

Project Note

  • Karte im Projekt vom Type Notiz

Role

Label

  • Analyst, Developer, Project Manager, …​

Assignee

  • Legt zu einer Issue den Bearbeiter/Verantwortlichen (Nutzer) fest

Mit einem GitHub Project und verschiedenen Sichten (Views) ist der Projektfortschritt mit seinen Iterationen und WorkItems (Issues) für alle Teammitglieder immer ersichtlich. Folgend ein Beispiel:

GitHub Projects - Beispiel: Überblick über alle Iterationen (Table view)
Abbildung 4. GitHub Projects - Beispiel: Überblick über alle Iterationen (Table view)

Dabei ist zu beachten:

  • Projekte und Meilensteine können wie Issues nach Fertigstellung geschlossen (bzw. wieder geöffnet) werden.

  • Issues können ebenfalls einen Fortschrittsbalken anzeigen, wenn im Kommentar Checklisten mit - [ ] task angelegt werden.

  • Issues können in Projekten zwischen den Zuständen mit Drag&Drop (Table View) oder durch bestimmte Schlüsselwörter (automatisiert, Status-Spalte) bewegt werden.

Hinweise zu Issues und Work Items

Beispiel mit Issues, Labels und Zuordnung zu Projekten und Meilensteinen.

  • Priorisierung von Work Items (Issues) nach Wichtigkeit (bspw. hoch, mittel, niedrig):

    • hoch: Work Items werden in die aktuelle Iteration aufgenommen

    • mittel: Work Items werden in die aktuelle oder nächste Iteration aufgenommen

    • niedrig: Work Items sind noch keiner Iteration zugeordnet oder dienen als Notiz einer weiteren Ausarbeitung.

    • Zeit und Ressourcen spielen ebenfalls eine Rolle, ob die Zuteilung der Work Items auf die aktuelle bzw. folgenden Iterationen erfolgt.

  • Es ist sinnvoll den Issues (Work Items) Asignees (Nutzer, Role) zuzuordnen, damit Klarheit über die Aufgabenzuteilung herrscht.

  • Für die Bezeichnungen der Issues hier im Beispiel als User Story X und Work Item X in Ihrem Repository bitte passendere verwenden.

  • Labels, die sich an den Rollen des OpenUP orientieren, helfen sie entsprechend zu filtern.

  • Die Issues dienen als Beispiele für die folgenden Hinweise zu User Stories, Projekten und Meilensteinen.

Übersicht der Issues
Abbildung 5. Übersicht der Issues
Hinweise zu User Stories und Issue-Referenzen

Verwendet man im Kommentar einer Issue die ID einer anderen Issue, taucht bei dieser ein entsprechender Verweis auf.

Im folgenden Beispiel ist in den Issues #15, #16, #17 und #18 die ID der gezeigten Issue #2 erwähnt worden. Diese enthält jetzt Verweise auf die genannten Issues.

Referenzen eines User Story (Issue) zu seinen Work Items (Issues)
Abbildung 6. Referenzen eines User Story (Issue) zu seinen Work Items (Issues)

Dies ist eine Möglichkeit, die aus User Stories (issue #2) extrahierten konkreten Work Items (Issues #15, #16, #17 und #18) zu referenzieren.

Hinweise zu Projekten (Projects) und Planung von Iterationen in GitHub

Die neuen GitHub Projects ermöglichen es innerhalb eines Projektes, die komplette Projektplanung mit allen Iterationen und zugehörigen Repositories abzubilden.

  • Planung, Zustände und Übersicht über die vergangenen, aktuelle und zukünftige Iterationen

  • Erfassung einer Complexity zu den Work Items (Issue) in den Iterationen

  • Verwaltung von Projektmitgliedern

  • Verwendung von Work Items (Issues) aus verschiedenen Repositories

  • Erstellung unterschiedlicher Sichten mit verschiedenen Schwerpunkten auf das Projekt

  • Erstellung von Diagrammen zum Zustand des Projektes

Die GitHub Projects sind in dieser Form noch relativ neu, so dass die Aufgaben noch nicht in allen Aspekten komplett angepasst sind. Ausführliche Informationen findet man unter folgenden Links:

Folgend zwei Beispiele für eine Übersicht über alle Iterationen und eine fokussierte Sicht auf die aktuelle Iteration:

GitHub Projects - Beispiel: Überblick über alle Iterationen (Table view)
Abbildung 7. GitHub Projects - Beispiel: Überblick über alle Iterationen (Table view)
GitHub Projects - Beispiel: Aktuelle Iteration (Board view)
Abbildung 8. GitHub Projects - Beispiel: Aktuelle Iteration (Board view)

Damit so ein Projekt im Team genutzt werden kann, legt der Repository-Eigentümer das neue Projekt an und läd die anderen Teammitglieder, wie auch zum Repository, dazu ein.

Ein neues Projekt anlegen:

  1. Neue Projekte werden über den Account-Button  Your projects gefolgt von New project angelegt:

    • Select a template: Table oder Board → Create

      GitHub Projekt anlegen - Template wählen
      Abbildung 9. GitHub Projekt anlegen - Template wählen

  2. Nach dem Anlegen, kann mit einem Klick auf den Titel @account untitled project der Namen des Projektes in bspw. Projektplan: Thema I1 geändert werden.

Teammitglieder zum Projekt einladen

  1. im Projekt oben rechts auf …​ klicken

  2. den Menüpunkt Settings → Manage access auswählen.

  3. über Invite collaborators können jetzt die Teammitglieder gesucht und hinzugefügt werden

    Als Rolle kann entweder Admin, Write oder Read ausgewählt werden.

Projekt in Repository verlinken:

  1. im (Team-)Repository in den Reiter Projects wechseln

  2. über den Button Link a project das zuvor angelegte Projekt auswählen

Iterationen hinzufügen:
Issues als Work Items aufnehmen:

  • Table view: Zeile mit +-Button

  • Board view: + Add item-Button (Spalte Todo)

    • per + → Add item from repository → Repository wählen → Issues auswählen → Add selected items

  • per Suche (Add item) → Repository Namen eingeben und auswählen → Issue direkt wählen oder per Add multipleItems gleich mehrere aus dem gewählten Repository auswählen

Complexity/Velocity im Projekt zu den Work Items (Issues) erfassen:

  1. Ein neues Feld über das + im Tabellenkopf (Table View) hinzufügen

  2. + New field wählen

    • Fieldname: Complexity

    • Field type: Number

  3. Jetzt können den Work Items entsprechende Werte zugewiesen werden. Nach diesen kann jetzt gruppiert, gefiltert und über Insights in Diagrammen genutzt werden.

Weitere Views hinzufügen:

  1. Mit dem Button + New view können weitere alternative Sichten als Table oder Bord hinzugefügt werden.
    Der Inhalt und das Aussehen der Views können über den kleinen ▼ neben dem View-Namen angepasst werden. Anpassungsmöglichkeiten wären: gruppieren, sortieren, filtern, extra Spalten und weiteres.

  2. Vorschläge für hilfreiche Views:

    • Overview: Table view, Gruppierung: Iteration

    • Current Iteration: Board view, Filter: iteration:@current

    • Current & Next Iteration: Table view, Filter: iteration:>=@current, Gruppierung: Iteration, Sortierung: Status

    • Backlog: Table view, Filer: no:iteration

Workflows anpassen:

  1. Im Projekt oben rechts auf …​ klicken

  2. Den Menüpunkt Workflows auswählen

  3. Hier kann (noch etwas eingeschränkt) das automatische Verhalten der Issues mit dem wechsel des zugehörigen Status angepasst werden.

Hinweise zu Meilensteinen (Milestone) in GitHub

  • Neue Meilensteine werden in der Issue-Ansicht (Reiter Issues) → Milestones über den Button New milestone abgelegt:

    Detailansicht eines Projektes

    • Title: bspw. Inception Phase

    • Due date (optional): geplantes Ende

    • Description (optional): Beschreibung

Übersicht der Meilensteine
Abbildung 11. Übersicht der Meilensteine

  • In der Meilensteinübersicht bzw. Detailansicht können wahlweise die offenen oder geschlossenen Meilensteine bzw. enthaltenen Issues angezeigt werden.

Detailansicht eines Meilensteins
Abbildung 12. Detailansicht eines Meilensteins

Aufgabe 3.1 - Üben

  1. Erstellen Sie in Ihrem privaten Repository htwd-se-example-project eine User Story als neue Issue mit dem Label user story an. Bspw.:

    Tabelle 5. User Stories
    Nr. Title Description

    1

    Dokumentation wie Code behandeln

    Als Entwickler möchte ich die Dokumentation wie Code behandeln, damit ich mich nicht in neue Tools einarbeiten muss.

  2. Erstellen Sie drei Work Items als neue Issues mit dem Label work item, wovon sich die zwei ersten auf die vorher angelegte User Story beziehen sollen. Legen Sie sich jeweils als zugeordneter Nutzer fest. Schauen Sie sich Ihre User Story (Issue) an, ob die Referenzen aufgetaucht sind. Bspw.:

    Tabelle 6. Work Items
    Nr. Title Description

    1

    Dateien der Dokumentation erstellen

    Erstellen der Dateien Dokumentation.adoc, Software.inc.adoc und Mitglieder.inc.adoc im AsciiDoc-Format im Ordner docs.

    2

    Ausgelagerte Dateiinhalte einbinden

    Einbinden (include) der Dateien für die Software und Mitglieder in die Dokumentation.

    3

    Datei .gitignore anlegen

    Einrichten des Git-Repositories zum Ignorieren von HTML- und PDF-Dateien.

  3. Erstellen Sie ein neues Projekt Projektplanung: Beispiel.

  4. Nehmen Sie Ihre eben erstellten Work Items (nicht die User Story) in das Projekt auf.

  5. Erstellen Sie ein neues Feld Complexity (numeric) und ein neues Feld Iteration mit einem wöchentlichen Zyklus.

  6. Vergeben Sie jedem Work Item einen Complexity Score.

  7. Weisen Sie zwei Work Items der aktuellen Iteration zu.

  8. Richten Sie sich zwei Sichten: Overview und Current Iteration ein.

    • Overview: Table view, Gruppierung: Iteration

    • Current Iteration: Board view, Filter: iteration:@current

  9. Erstellen Sie im Projekt (Sicht: Overview) ein Work Item als neue Issue mit dem Label work item und nehmen Sie es anschließend in Ihre aktuelle Iteration auf:

    Tabelle 7. Work Items
    Nr. Title Description

    4

    Termin mit Auftraggeber vereinbaren

    Terminanfrage per E-Mail oder Telefon an den Auftraggeber.

    • erstes Meeting mit dem Auftraggeber

    • Vorstellung des Teams

  10. Schließen Sie ein Work Item (Issue) in der Issue-Ansicht (oder per Commit) und schauen Sie sich die Änderung im Projekt bzw. den enthaltenen Views (Sichten) an.

Hinweise für den Beleg

Für den Schwerpunkt der Work Item- und Iterationsverwaltung mit GitHub Issues/Projects sind durch die Fachaustausche in SE II einige ergänzende und alternative Tools von Studenten empholen worden:

Seitenübersicht

Praktika - SE I

Praktika - SE II