Organisation der Arbeitsabläufe im Dokumentationsteam

Fedora-Dokumentationsteam Last review: 2023-04-24
Dieser Leitfaden stellt Docs-Mitgliedern und angehenden Mitwirkenden die Liste der Labels und Kategorien vor, die mit Issues und Merge Requests im GitLab Docs-Repository verknüpft sind.

Das Fedora Docs-Team einigte sich auf eine Organisation der Arbeitsabläufe, die auf den beiden zentralen Seiten zusammenläuft:

GitLab-Dashboard

Offene Merge Requests auf GitLab

Issue-Board und Labels

Es gibt vier Labels, die den Status eines Issue-Tickets klassifizieren.

  • Triage: Das Problem ist gelabelt, aber noch niemandem zugewiesen. Möchten Sie die Bearbeitung übernehmen? Weisen Sie sich gerne selbst zu und ändern Sie den Status auf „In progress“.

  • In progress: Jemand wurde mit diesem Problem beauftragt und es wird daran gearbeitet.

  • Support needed: Es wurden bereits Maßnahmen ergriffen, aber jemand muss den derzeitigen Beauftragten unterstützen oder die Aufgabe ganz übernehmen.

  • Approval needed: Dies ist eine wichtige Änderung und bedarf der Genehmigung durch eine andere Person als den Bearbeiter. Sie können die Genehmigung gerne übernehmen, damit der Bearbeiter die Änderungen anschließend zusammenführen kann.

Die Seite „Open Merge Requests“ enthält kein Dashboard. Beim Öffnen der Seite „Open Merge Requests“ sehen Sie auf einen Blick alle zugewiesenen Labels eines offenen Merge Requests.

Darüber hinaus gibt es drei Labels, die den Typ eines Issue-Tickets klassifizieren.

  • Major change: Dies ist eine wichtige Änderung auf der/den Dokumentationsseite(n). Sie erfordert einen Merge Request und muss von einer anderen Person als dem Bearbeiter genehmigt werden, bevor sie zusammengeführt werden kann.

  • Minor change: Es handelt sich lediglich um eine geringfügige Änderung auf der/den Dokumentationsseite(n). Sie bedarf keiner Genehmigung und kann direkt übernommen werden (ein Merge Request ist nicht zwingend erforderlich).

  • Internal task: Dies ist eine interne Aufgabe von Fedora Docs, die keine Änderung, Fehlerbehebung oder Aktualisierung einer Dokumentationsseite/eines Dokumentationsinhalts darstellt. (Beispiel: Vorbereitung eines Meetings oder Auswertung einer Umfrage).

Jedes Issue-Ticket und jeder offene Merge Request muss zusätzlich mit einem dieser drei Labels versehen werden. Die Typ-Labels ändern sich innerhalb des Arbeitsablaufs nicht.

Neben Status- und Typ-Labels können Issue-Tickets und Merge Requests zusätzlich als „good first issue“ gekennzeichnet werden. Möchten Sie zu Fedora Docs beitragen? Hier ist Ihre Chance. Kommentieren Sie einfach eines der Issues, das Sie sich selbst zuweisen möchten.

Darüber hinaus gibt es ein zusätzliches Label für Merge Requests, die möglicherweise mehrere Zweige betreffen und daher Folge-Merge-Requests oder Cherry-Picks erfordern. Das Label multiple MR likely stellt sicher, dass alle betroffenen Zweige identifiziert und aktualisiert werden und dass Merge Requests nicht ohne vorherige Prüfung zusammengeführt werden.

Erstellung von Issue-Tickets und Merge Requests

Es gibt zwei Möglichkeiten, Issue-Tickets und Merge Requests zu erstellen: extern und intern.

  • Externe Tickets werden von Personen außerhalb des Fedora-Docs-Teams erstellt, die sie in GitLab geöffnet oder die Knöpfe „Report an issue“ (erstellt Tickets) / „Edit this page“ (erstellt Merge Requests) auf einer beliebigen Fedora-Docs-Seite (oben rechts) verwendet haben. Tickets erscheinen ohne Label in der Liste „Offen“ im Dashboard. Merge Requests erscheinen ebenfalls ohne Label auf der Seite „Open Merge Requests“.

  • Wurde das Ticket intern erstellt, hat es ein Mitglied des Dokumentationsteams geöffnet. Im Idealfall weist dieses Mitglied bereits ein Type-Label zu und verschiebt das Ticket in die Liste „Triage“, wo es auf die Zuweisung eines Bearbeiters warten kann. Dasselbe gilt für Merge Requests, allerdings verfügen diese nicht über Drag-&-Drop-Listen, und die Bezeichnung „Triage“ muss – wie das Type-Label – manuell festgelegt werden. Alternativ kann das erstellende Mitglied dem Ticket/Merge Request bereits einen Bearbeiter zuweisen und das Ticket anschließend per Drag & Drop in die Liste „In progress“ im Dashboard verschieben (wodurch das Label „In progress“ hinzugefügt wird) oder, falls es sich um einen Merge Request handelt, das Label „In progress“ manuell hinzufügen.

Im Dashboard lassen sich Tickets per Drag & Drop in den Listen verschieben. Die Status-Labels ändern sich entsprechend. Wird ein Ticket beispielsweise per Drag & Drop von „Triage“ nach „In progress“ verschoben, ändert sich das Status-Label von „Triage“ zu „In progress“. Daher müssen die persistenten Type-Labels nur einmalig manuell festgelegt werden, wenn das Ticket neu erstellt wird. Dies gilt nicht für Merge Requests auf der Seite „Open Merge Requests“. Beim Erstellen eines Tickets im Dashboard werden Sie gefragt, wo Sie das Ticket erstellen möchten. Wenn Sie sich nicht sicher sind, wo Sie das Ticket erstellen sollen, wählen Sie „Fedora / Fedora Docs / Docs Website / Fedora Docs Pages“. Sie finden diese Option in der Projektliste („Select a project“), die angezeigt wird, wenn Sie auf „Create ticket“ klicken. Später wird diese Option als „fedora/docs/docs-website/pages“ angezeigt.

Der Arbeitsablauf

Minor change

Wenn Änderungen von Mitgliedern des Dokumentationsteams durchgeführt werden und es sich eindeutig um kleinere Änderungen handelt, können diese per Direkt-Commit ohne Merge Request oder Ticket vorgenommen werden. Erstellen externe Benutzer einen Merge Request für kleinere Änderungen, mergen die Mitglieder des Dokumentationsteams diesen umgehend, nachdem sie sich die Bearbeitung zugewiesen und den Merge Request geprüft haben. Es ist jedoch immer zu prüfen, ob eine Änderung mehrere Zweige betrifft.

Wenn mehrere Zweige von einer „Minor change“ betroffen sind, ist ein direkter Merge/Commit nur dann zulässig, wenn Sie den Merge/Commit und die Cherry-Picks gleichzeitig in alle betroffenen Zweige durchführen. Im Zweifelsfall fügen Sie zusätzlich zum Label „Minor change“ das Label „multiple MR likely“ hinzu und lassen Sie den Merge Request für Diskussionen offen.

Abhängig vom weiteren Verlauf der Diskussion wird das Label „multiple MR likely“ entfernt, wenn keine weiteren Zweige betroffen sind und der Merge oder Commit durchgeführt werden kann. Sind hingegen weitere Branches betroffen, wird der Merge oder Commit durchgeführt und gleichzeitig ein Cherry-Pick für alle betroffenen Zweige vorgenommen. Ziel ist es, dass ein Merge Request erst dann von der Seite „Open Merge Requests“ verschwindet, wenn die Aktualisierung aller betroffenen Zweige abgeschlossen ist.

Findet die Diskussion innerhalb eines Issue-Tickets statt (mit Commits anstelle von Merge Requests oder mit mehreren Merge Requests, die in einem Ticket zusammengeführt werden) und nicht innerhalb eines einzelnen Merge Requests, können der Commit und die Cherry-Picks separat durchgeführt werden.

Der Arbeitsablauf für eine Minor change (kleinere Änderung) ist wie folgt:

  1. Wenn es sich nur um einen Commit handelt, der eindeutig eine „Minor change“ darstellt, führen Sie ihn einfach aus. Wenn Sie wissen, welche Zweige betroffen sind und ob Sie den Commit sowie alle zugehörigen Cherry-Picks durchführen können, legen Sie los. Falls Sie nicht genügend Zeit haben, um die Aufgabe abzuschließen, gehen Sie wie folgt vor:

  2. Bestimmen Sie den Typ und weisen Sie das entsprechende Type-Label („Minor change“, „Major change“, „Internal task“ – hier: Minor change) dem bestehenden Merge Request oder Ticket zu. Falls noch kein Eintrag existiert, erstellen Sie einen. Wenn Sie sich nicht sicher sind, was Sie erstellen sollen, erstellen Sie ein Ticket.

  3. Verschieben Sie neue Vorgänge in die Liste „Triage“ (die, wie oben erläutert, automatisch das Status-Label „Triage“ erhält) oder das Label „Triage“ wird manuell hinzugefügt, wenn es sich um einen Merge Request handelt.

  4. Das Issue-Ticket oder der Merge Request kann einem Mitglied zugewiesen werden, das die Bearbeitung übernimmt. Sobald eine Zuweisung erfolgt ist, muss das Ticket auf „In progress“ gesetzt werden (diese Änderung muss bei Merge Requests manuell vorgenommen werden).

  5. Es gibt mehrere Möglichkeiten.

    1. Der zuständige Mitarbeiter schließt das Ticket/den Merge Request ab und ändert dessen Status entsprechend auf „Closed“. Wenn mehrere Zweige geändert werden sollen und der Fall innerhalb eines Merge Requests bearbeitet wird, müssen alle Zweige gleichzeitig geändert werden.

    2. Alternativ benötigt der Bearbeiter Unterstützung oder zusätzliche Meinungen: Das Ticket/der Merge Request wird auf „Support needed“ gesetzt, um Unterstützer zu finden (die gegebenenfalls als zusätzliche Bearbeiter benannt werden können). Sobald genügend Unterstützer gefunden wurden, wird das Ticket/der Merge Request wieder auf „In progress“ gesetzt. Verwenden Sie „Support needed“, um eine Diskussion im Ticket/Merge Request anzuregen und zusätzliche Meinungen einzuholen. Nach Abschluss aller Arbeiten kann das Ticket/der Merge Request auf „Closed“ gesetzt werden. Wenn mehrere Zweige geändert werden müssen und der Fall innerhalb eines Merge Requests bearbeitet wird, müssen alle Zweige gleichzeitig geändert werden. Mitglieder können das Problem neu zuweisen (z.B. wenn jemand anderes mehr Erfahrung mit der Aufgabe hat oder mehr Zeit investieren kann).

    3. Kann der Bearbeiter das Issue nicht mehr unterstützen, ändert er entweder das Label des Issues in „Support needed“ und sucht einen neuen Bearbeiter oder er vermerkt die erledigten und die verbleibenden Arbeiten, entfernt den Bearbeiter und ändert den Status in „Triage“.

Major change (größere Änderung)

„Multiple MR likely“ kann in „Major changes“ umgewandelt werden, die ein Ticket oder einen Merge Request erfordern.

Der Arbeitsablauf für eine größere Änderung sieht wie folgt aus:

  1. Ermitteln Sie den Typ und setzen Sie das Label des Merge Requests oder Issue-Tickets auf Major change.

  2. Verschieben Sie neue Issues in die „Triage“-Liste, oder fügen Sie das „Triage“-Label manuell hinzu, falls es ein Merge Request ist.

  3. Das Issue-Ticket oder der Merge Request kann anderen Mitgliedern neu zugewiesen werden. Sobald eine Zuweisung erfolgt ist, ändert sich der Status des Tickets zu „In progress“ (diese Änderung wird bei Merge Requests manuell vorgenommen).

  4. Es gibt mehrere Möglichkeiten.

    1. Der Bearbeiter beendet die aktive Bearbeitung* des Tickets/MR und ändert den aktuellen Status auf „Approval needed“.

    2. Alternativ benötigt der Bearbeiter Unterstützung oder zusätzliche Meinungen. Das Ticket/der Merge Request wurde auf „Support needed“ gesetzt, um Unterstützer zu finden. Sobald sich genügend Unterstützer gemeldet haben, kann der Status wieder auf „In progress“ gesetzt werden. „Support needed“ kann auch genutzt werden, um eine Diskussion im Ticket/Merge Request anzuregen und weitere Meinungen einzuholen. Nach Abschluss der Diskussion kann das Ticket/der Merge Request auf „Approval needed“ gesetzt werden. Der zuständige Bearbeiter sollte durch jemanden ersetzt werden, der mehr Erfahrung mit der nächsten Aufgabe hat oder mehr Zeit investieren kann.

Sind mehrere Zweige betroffen, fügen Sie das Label „multiple MR likely“ hinzu. Ist dieses Label vergeben, müssen in der Ticket-/Merge-Request-Diskussion alle betroffenen Zweige identifiziert werden. Abschließend muss der Merge Request per Cherry-Pick in alle betroffenen Zweige übertragen werden. Müssen mehrere Zweige geändert werden, müssen alle Änderungen gleichzeitig durchgeführt werden.

Verwenden Sie für Inhalte nicht den „stg“-Zweig. Arbeiten Sie in separaten Forks und Zweigen für das jeweilige Issue, an dem Sie arbeiten.

Internal task (interne Aufgabe)

Interne Aufgaben sind flexibel. Sie starten in „Open“ oder „Triage“ und wandern durch „Triage“, „In progress“, „Support needed“ bis zu „Closed“.

Die Rolle des wöchentlichen Meetings

Das wöchentliche Docs-Meeting dient dazu, ungewöhnliche oder unregelmäßig auftretende Probleme und Aufgaben zu identifizieren und anzugehen. Die Organisation des Arbeitsablaufs hingegen ist darauf ausgelegt, die standardisierten täglichen Abläufe der Fedora-Dokumentation zu verwalten.

Die aktuellen Issue-Tickets und Merge Requests der Organisation des Arbeitsablaufs können zu regelmäßigen Themen im wöchentlichen Meeting werden.

  • Prüfen Sie, ob es im Arbeitsablauf unvorhergesehene Entwicklungen gibt, die einer Besprechung bedürfen.

  • Identifizieren und weisen Sie Issue-Tickets und MRs zu, die länger als zwei Wochen nicht zugewiesen sind, und besprechen Sie diejenigen, die einen Monat nach ihrer Zuweisung noch offen sind.

  • Verwenden Sie das Label Meeting für Probleme oder Merge Requests, die im Docs-Meeting besprochen werden sollen.

Want to help? Learn how to contribute to Fedora Docs ›