Projektmanagement

Issues

Issues sind dazu gedacht, die Arbeit zu planen und Ideen, Feedback, Aufgaben oder Bugs zu verfolgen. Hat man also eine Idee für ein neues Feature oder stellt fest, das etwas in der überhaupt nicht oder zumindest nicht wie erwartet funktioniert, sollte ein Issue erstellt werden.

Im Northware Repository gibt es vordefinierte Issue-Templates, um den übersichtlichen Entwicklungsprozess zu unterstützen.

• Bug melden: Während der Entwicklung oder der Nutzung der App ist ein (schwerwiegender) Bug aufgefallen. Etwas funktioniert nicht und führt so zu einem Fehler. Der Issue wird automatisch mit bug gelabeled.
• Problem melden: Während der Entwicklung oder Nutzung der App ist aufgefallen, das etwas nicht wie vorgesehen funktioniert. Der Issue wird automatisch mit invalid gelabeled.
• Neues Feature: Ein Vorschlag für ein neues Feature, das es bisher so noch nicht in der App gibt oder das ein bestehendes Feature erweitert. Der Issue wird automatisch mit enhancement gelabeled.
• Erweiterung der Dokumentation: Ein fertiges Feature soll in dieser Dokumentation erklärt werden. Der Issue wird automatisch mit docs-wanted gelabeled.
• Security Vulnerability Tracking: Dependabot hat eine Security Vulnerability gefunden. In diesem Issue wird getracked, was getan werden kann, um die Vulnerabilty zu beseitigen. Der Issue wird automatisch mit security gelabeled.

tipp

Die Issues sollten neben den voreingestellten Labels auch die Labels von Apps oder Packages erhalten, die sie beeinflussen würden.

Jeder Issue wird automatisch dem Projekt Northware New mit dem Status Triage zugeordnet. Der Nutzer muss dann entscheiden, welchen Status der Issue bekommen soll. Mehr zum Projekt.

Wenn die Arbeit an dem Issue beginnt sollte der Branch auf dem die Änderungen durchgeführt werden unter Development verlinkt werden. Wenn die Arbeit später mit einem Pull Request verbunden wird, wird dieser mit dem Issue verlinkt und das mergen des PR schließt den Issue.

Milestones

GitHub Milestones können verwendet werden, um Issues und Pull Requests zu gruppieren und den Fortschritt dieser Gruppe nachzuverfolgen. Wenn mehrere Issues und Pull Requests inhaltlich einem größeren Teil des Projektes (einem Meilenstein) zuzuordnen sind, können und sollen diese Issues und PR's einem Meilenstein zugeordnet werden.

Pull Requests

Wenn Änderungen von Branches auf den main Branch gemerged werden sollen, muss dafür ein Pull Request angelegt werden. Auch für die Pull Reuests gibt es ein Template, das vorsieht, dass im oberen Teil die Änderungen beschrieben werden, außerdem sollen hier Issues verlinkt werden, die mit diesem PR geschlossen werden sollen oder damit in Zusammenhang stehen. So kann ein konsequentes referenzieren und der automatische Isue-Close Vorgang sichergestellt werden.

warnung

Wenn Issues nur wegen der Referenzierung oder automatisch verlinkt werden, obwohl der PR den Issue nicht oder nicht vollständig löst, muss der Issue manuell wieder geöffnet werden.

Der Wokflow Labeler labeled den Pull Request basierend auf den geänderten Dateien mit den richtigen apps/ oder packages/ Labels.

Jeder Pull Request wird automatisch dem Projekt Northware New mit dem Status Triage hinzugefügt und muss vom Nutzer ggf. angepasst werden. Pull Requests an denen noch gearbeitet wird sollen den Status In Progress erhalten. Wenn die Änderungen des PR noch auf ein Review warten, erhalten sie den Status For Review. Wenn der PR gemerged wurde, wird er automatisch dem Status Done zugeordnet.

Labels

Mit Labels lassen sich Issues und Pull Requests kategorisieren. Labels sind bei der Entwickung von Northware sehr wichtig, denn auf Basis dieser Kennzeichnungen werden teilweise Workflows abgearbeitet und Filter gesetzt.

Es gibt bei der Entwicklung von Northware Labels, die den Typ eines Issues oder Pull Requests kennzeichnen (z.B. enhancement), Labels die betroffene Codeteile (apps/ und packages/ Labels) und Labels die von Bots und Workflows verwendet werden (z.B. dependencies und github-actions).

Type Labels

Label	Beschreibung
bug	Es geht um einen (schwerwiegenden) Bug, der einen Fehler verursacht und der möglichst bald behoben werden sollte.
invalid	Etwas in der App funktioniert nicht so, wie es soll. Dieses Problem sollte behoben werden. Da durch dieses Problem kein (schwerwiegender) Fehler entsteht ist die Bearbeitung weniger dringend als bei den bugs.
enhancement	Neues Feature oder neue Idee
docs-wanted	Das, was in diesem Issue beschrieben ist, sollte in die Dokumentation aufgenommen werden. Wenn die Dokumentation zu diesem Thema erweitert wurde, sollte dieses Label entfernt werden. Die Dokumentation kann zusammen mit den Änderungen im Code verfolständigt werden, wenn für die Änderung der Dokumentation ein extra Issue erstellt werden, sollte dieser nach Vervollstädigung der Dokumentation mit apps/docs versehen werden.
security	Dependabot hat eine Security Vulnerabilty festgestellt, die mit diesem Issue nachverfolgt wird.
duplicate	Ein Issue oder Pull Request zu diesem Thema existiert bereits.
wontfix	An diesem Issue/PR wird nicht mehr gearbeitet.

Labels für Apps

Um eine konsequente Zuordnung des Issues/PRs zu betroffenen Codeteilen zu erzielen, erhält jede App in dem Projekt (Dateipfad apps/*) ein eigenes Label. Nach dieser Kennzeichnung wird im Projekt gefiltert.

info

Für die Pull Requests gibt es einen Labeler Workflow, der basierend auf den geänderten Dateien Labels der Apps/Packages und anderer Dateipfade zuweist. Bei Issues muss diese Kennzeichnung manuell erfolgen. Wenn ein neues Label für eine App, ein Package oder einen anderen Ordner angelegt wird, muss die labeler.yml (Konfigurationdatei) bearbeitet werden. Mehr Infos zu Labeler

Label	Beschreibung
apps/northware-cockpit	Dieser Issue/PR ändert etwas an der App Northware Cockpit
apps/northware-finance	Dieser Issue/PR ändert etwas an der App Northware Finance
apps/northware-trader	Dieser Issue/PR ändert etwas an der App Northware Trader
apps/docs	Dieser Issue/PR ändert etwas an der Documentation. Dieses Label soll verwendet werden, wenn es tatsächlich um die Änderung von Code in der Dokumentation geht. Wenn es nur darum geht, die Änderung der Docs zu verlangen, soll das Label docs-wanted verwendet werden.

Labels für Packages und die API

Auch die einzelnen Packages (Dateipfad packages/*) sollen aus den gleichen Gründenn wie die Apps jeweils eigene Labels erhalten. Sie alle erhalten die gleiche Farbgestaltung mit der Textfarbe black und der Hintergrundfarbe #F0B9F8.

Label	Beschreibung
api	Dieser Issue hat Auswirkungen auf die API (Neon DB und/oder Drizzle). Der Code der API ist nicht (vollständig) im Github Repository zu finden. Möglicherweise hat ein Eintrag mit diesem Label auch Auswirkungen auf das packages/database
packages/theme	Dieser Issue/PR ändert etwas an dem @northware/theme Package
packages/ui	Dieser Issue/PR ändert etwas an dem @northware/ui Package
packages/auth	Dieser Issue/PR ändert etwas an dem @northware/auth Package
packages/database	Dieser Issue/PR ändert etwas an dem @northware/database Package
packages/tailwind-config	Dieser Issue/PR ändert etwas an dem @northware/tailwind-config Package
packages/eslint-config	Dieser Issue/PR ändert etwas an dem @northware/eslint-config Package

Labels für andere Dateipfade

Label	Beschreibung
turborepo	Dieser Issue/PR ändert etwas der Turborepo-Konfiguration bzw. an den Dateien im Root-Verzeichnis
github-management	Dieser Issue/PR ändert etwas an der Konfiguration für GitHub. Das kann Dateien im .github/ Ordner, das Northware New Projekt und Einstellungen des Repositories betreffen.

Labels für Bots und Workflows

Label	Beschreibung
dependencies	Mit diesem Pull Request wird etwas in Bezug auf Dependencies geändert, das kann die automatischen Updates von Dependabot oder manuelle Veränderungen betreffen.
github-actions	Dieser Issue/PR wurde von einem GitHub Actions Workflow ausgelöst.

Das Northware New Projekt

Das Projekt Northware New wird genutzt um einen besseren Überblick über die Arbeit an am Northware Projekt zu geben. Es besteht aus mehereren Ansichten, die offene und geschlossene Issues und Pull Requests so Filtern, das Entwickler den Überblick behalten und einfacher an dem Repository arbeiten können.

Status

Neue Issues und Pull Requests werden automatisch dem Northware New Projekt mit dem Status Triage. Der Nutzer ist dafür verantwortlich, das die Einträge dem richtigen Status zugeordnet werden. Die Projekt Workflows unterstützen dabei.

Status	Beschreibung
Triage	Alle Einträge, die neu zu dem Projekt hinzugefügt wurden. Diese Einträge müssen noch hinsichtlich Labeling und Status-Zuordnung eingeordnet werden.
Backlog	Ideen, an denen später einmal gearbeitet werden kann. Die Arbeit an diesen Einträgen ist nicht so wichtig wie die Arbeit an den Todo Einträgen. (Nur für Issues)
Todo	Einträge an denen als nächstes mal gearbeitet werden sollte. (Nur für Issues)
In Progress	An diesen Einträgen wird gerade gearbeitet. (Für Issues und für Pull Requests, die noch nicht abgeschlossen werden konnten)
For Review	Einträge, die noch einmal betrachtet werden sollen. Meistens Pull Requests, die von Bots oder Workflows erstellt wurden und zum mergen bereitstehen.
Done	Einträge die abgeschlossen sind (gemergete oder ohne merge abgeschlossene Pull Requests und abgeschlossene Issues).

Ansichten

Triage

Wie oben beschrieben, werden neue Issues und Pull Requests automatisch mit dem Status Triage zu dem Projekt hinzugefügt. In diesem Status sollen die Einträge aber nicht bleiben sondern einem anderen Status zugeordnet werden. Die Triage-Ansicht zeigt alle Einträge an, die noch den Status Triage haben und daher noch hinsichtlich Labeling und Status-Zuordnung eingeordnet werden müssen.

All Items

Diese Ansich ebthält alle Einträge, die das Northware New Projekt enthält

Apps

In dieser Ansicht werden alle Einträge angezeigt, die ein apps/ Label haben und daher eine Änderung einer oder mehrerer Apps bewirken.

Packages

In dieser Ansicht werden alle Einträge angezeigt, die ein packages/ Label haben und daher eine Änderung einer oder mehrerer Packages bewirken.

API

In dieser Ansicht werden alle Einträge angezeigt, die das api Label haben und daher eine Änderung der API bedeuten. Das kann mit Änderungen an der Neon Database oder am Drizzle ORM oder anderen API-bezogenen Microservices zu tun haben.

No App/No Package

In dieser Ansicht werden alle EInträge angezeigt, die nicht mit einer Änderung einer App, eines Packages oder der API zutun haben oder bei denen diese Kennzeichnung vergessen wurde.

Done

In dieser Anzeige werden alle Einträge angezeigt, die bereits erledigt sind. Es handelt sich also um geschlossene oder gemergete Issues und Pull Requests.