Einreichung von Problemen

Diese Seite ist für Personen geschrieben, die bei der Einreichung von Problemen im GitHub-Issue-Tracker helfen.

Vorrede

• Jedes Projekt hat begrenzte Ressourcen, der Unterschied zwischen Projekten wird die Schwelle sein.
• Jedes Projekt sollte klare Ziele haben. Für Ansel ist es, Sammlungen von RAW-Bildern auf einem Desktop-Computer von einem Endbenutzer zu verwalten, zu bearbeiten und zu exportieren, der kein CLI-Benutzer ist, aber visuelle Bildqualität über alles setzt.
• Jedes Projekt hat Overhead, das sind Maßnahmen, die ergriffen werden, um die Ziele zu erreichen, obwohl sie nicht direkt das Ziel sind und daher minimal bleiben sollten. Für Ansel ist dies die Wartung der Website, Dokumentation, Server, nächtlich gebaute Pakete, Code-Bereinigungen, Debugging, Regressionstests, plattformübergreifende Unterstützung, Problemtriage usw.
• Ziele und Overhead sollten in Form von Aufgaben ausgedrückt werden, die zur Lösung von Problemen (Issues) ausgeführt werden müssen. Wenn es kein zu lösendes Problem gibt, dann gibt es keine Arbeit zu erledigen: Status quo ist auch großartig, erstellen Sie keine Arbeit um der Arbeit willen.
• aufgrund der Ressourcenbeschränkungen müssen Aufgaben nach ihrer Priorität geordnet werden.

Das folgende Dokument zielt darauf ab, diese Priorität zu definieren.

Ansel wurde von Darktable abgezweigt, weil Darktable kein klares Ziel, kein Prioritätsmanagement hat, und der Overhead nimmt jedes Jahr zu, was das Markenzeichen von Burn-Out-Fabriken ist und auf mittlere Sicht nicht nachhaltig ist.

Definierung guter Issues

Projektmanagement funktioniert besser mit SMART-Aufgaben. S.M.A.R.T. steht für:

• Spezifisch (z. B. finden der URI von Bildern, die Ansel auf dem Dateisystem exportiert hat, und sie öffnen)
• Messbar (z. B. Anzahl der Klicks/Schritte, die erforderlich sind, CPU-Zeit um die Aufgabe auf einer Zielplattform durchzuführen)
• Handlungsfähig/Realisierbar (z. B. kann auf der aktuellen Codebasis mit nur minimalen Umschreibungen integriert werden, benötigt nur ein paar hundert Codezeilen)
• Relevant/Angemessen (z. B. ist Teil eines ziemlich allgemeinen fotografischen Arbeitsablaufs, würde von einem signifikanten Teil der Benutzer verwendet werden)
• Zeitgebunden (z. B. benötigt maximal 70 Mannstunden).

Ein gutes Issue ist eines, das zu einer SMART-Aufgabe führt. Für Ansel bedeutet das, sich auf ein klar definiertes Problem zu konzentrieren, das einen klar definierten Schritt im Bildbearbeitungs-Workflow betrifft (“Ich habe Probleme, X zu tun, weil Y, und ich möchte Z erreichen”).

Fragen und allgemeine Diskussionen sollten auf https://community.ansel.photos stattfinden.

Schlechte Issues sind:

• zu allgemein (“Arbeitsablauf automatisieren”, “UX verbessern”),
• Konzentration auf die Mittel (“neuronales Netzwerk verwenden”, “Tonkurve erweitern”) statt auf das Ziel (“den Himmel maskieren”, “Sättigung selektiv steuern”),
• außerhalb des Anwendungsbereichs (“auf Android portieren”, “zu Qt wechseln”, “zu Vulkan wechseln”)
• betreffen Drittanbieterbibliotheken/-projekte (Rawspeed, Libraw, Exiv2, Lensfun, GPhoto2, Gtk, etc.),
• zu subjektiv (“bitte macht das wie bei der anderen Software, die ich in der Vergangenheit genutzt und wirklich gemocht habe”). Was Benutzer A gefällt, wird von Benutzer B abgelehnt, damit können wir nicht arbeiten.

Anmerkung: Einige Issues könnten nach mehr Code klingen, während sie eigentlich bessere Dokumentation der aktuellen Funktionen oder leichte GUI-Anpassungen (Umbenennen von Labels, Neuanordnung von Widgets) brauchen. Das sollte man im Kopf behalten, bevor man loslegt.

Prioritäten definieren

In einer idealen Welt würden Aufgaben (also gute Issues) linear zur To-Do-Liste hinzugefügt werden, sobald Meilensteine erreicht sind, und ihr Codeprodukt würde für einige Wochen getestet, während der Code sonst eingefroren bleibt, bis sichergestellt ist, dass alles hält, in welchem Fall wir den Code entfrieren und zur nächsten Aufgabe in der To-Do-Liste übergehen würden.

Das Problem ist, dass dies bedeutet, dass alle für die Testphase an Deck sein müssen, sodass der Code nicht zu lange eingefroren bleibt. Da das nicht passiert (Menschen machen Urlaub, haben Kinder, ziehen um, wechseln den Job, führen ein Leben…), müssen wir das Testen des Produkts aus vorherigen Aufgaben parallelisieren, während wir an der nächsten arbeiten, um effizient zu sein.

Das bedeutet, dass die To-Do-Liste nicht linear ist und einige wichtige Dinge dynamisch hinzugefügt oder entfernt werden können, abhängig von dem, was passiert. Das Problem besteht dann darin zu bestimmen, was wichtig genug ist, um den Zeitplan zu stören.

Es gibt keine endgültige Regel hier, daher musst du dein bestes Urteilsvermögen einsetzen, aber es gibt einige Faustregeln:

• Etwas, das kürzlich kaputt gegangen ist (eine Regression) ist leichter zu erkennen und früher zu reparieren, sodass es im großen Ganzen weniger Arbeit sein könnte, es früher zu erledigen,
• Etwas, das das gesamte Funktionieren der Software verhindert (Absturz, beschädigte Ausgabedateien, Datenverlust) ist kritisch genug, um Vorrang vor Verbesserungen und kosmetischeren Korrekturen zu haben,
• Etwas, das eine große Anzahl von Benutzern betrifft und für das keine Lösung gefunden werden kann, hat ebenfalls Vorrang.

Im Gegenteil, alles, was eine kleine Anzahl von Benutzern betrifft, oder nischen/spezifische Funktionen, oder kleinere Ärgernisse, die umgangen werden können, sind nicht kritisch genug, um eine Unterbrechung des Zeitplans zu rechtfertigen. Diese werden in der Warteschlange in einer First-In/First-Out-Weise hinzugefügt.

Ansel hat 4 Prioritätsstufen, die als Issue-Tags festgelegt sind:

• priorität: kritisch: Beeinflusst grundlegende und Kernfunktionen der Software so, dass sie überhaupt nicht funktioniert,
• priorität: hoch: Beeinflusst grundlegende und Kernfunktionen der Software so, dass die Benutzerfreundlichkeit stark beeinträchtigt wird,
• priorität: mittel: Beeinflusst grundlegende und Kernfunktionen der Software so, dass die Benutzerfreundlichkeit leicht beeinträchtigt wird (Umgehungslösungen verfügbar),
• priorität: niedrig: Beeinflusst optionale und nischenbezogene Funktionen

Meilensteine definieren

Modulparameter werden als binäre Blobs gespeichert. Wir handhaben diese, indem wir ihre Bitgröße verwalten. Wenn ein neuer Parameter hinzugefügt wird, müssen wir Code schreiben, um die Konvertierung zu handhaben, das heißt, die unterschiedliche Bitgröße des Parameter-Blobs, und wir erhöhen die interne Versionsnummer der Modulparameter. Es wird kein Code für die Rückwärtskompatibilität geschrieben, so dass Bilder, die mit neueren Modulen bearbeitet wurden, in älteren Modulen nicht geöffnet werden können. Modulparameter werden auch in Stilen, Voreinstellungen und XMP-Dateien verwendet.

Aus diesen Gründen muss jedes Issue, das zur Hinzufügung von Parametern in Module führen würde (entweder die Bildverarbeitungsmodule im Dunkelraum oder die Lichttischmodule, die den Export und die Metadaten bearbeiten), die Rückwärtskompatibilität brechen und muss für die nächste große Version der Software geplant werden (1.0, 2.0, 3.0 usw.). Das bedeutet, dass nur GUI- und Verhaltensänderungen innerhalb derselben Hauptversion erlaubt sind und für die nächste Nebenversion geplant werden können (0.1, 0.2, 0.3, dann 1.1, 1.2, 1.3 usw.).

Ansel hat zu jeder Zeit nur 2 Meilensteine: die nächste Nebenversion und die nächste Hauptversion.

Schwierigkeit definieren

Schwierigkeit steht in direktem Zusammenhang mit dem erforderlichen Arbeitsaufwand für eine Aufgabe, das heißt:

• die Anzahl der zu schreibenden Codezeilen,
• die Anzahl der zu ändernden Dateien,
• die Wahrscheinlichkeit, bestehende Funktionen zu zerstören, was zu zusätzlichem Testaufwand führt,
• das Vorhandensein ähnlicher Funktionen oder schriftlicher Theorie zur Erreichung der Aufgabe,
• der Aufwand, Änderungen und Funktionen zuverlässig über Betriebssysteme hinweg zum Laufen zu bringen.

Die Schwierigkeit genau abzuschätzen, kann nur ein erfahrener Entwickler tun.

Natur definieren

Die Natur der Issues wird mit Labels behandelt. Wir haben:

• Rückschläge (Dinge, die früher funktionierten, aber durch relativ neue Änderungen kaputt gingen),
• Bugs (Dinge, die in den letzten Jahren nie funktionierten),
• Verbesserungen (Dinge, die verbessert oder hinzugefügt werden müssen),
• Nichtbeheben (kein Bug, sondern eine Design- oder Konstruktionsentscheidung oder Notwendigkeit, die durch Fremdabhängigkeiten auferlegt wird),
• Frage (sollte nicht auf Github sein, sondern auf https://community.ansel.photos),
• Duplikat (bereits gemeldetes Issue),
• Unklar (Issue kann nicht verstanden werden),
• Ungültig (Issue ist “schlecht” gemäß der obigen Definition eines guten Issues).

Prioritäten sind relativ

Siehe https://www.youtube.com/watch?v=8fnfeuoh4s8 . Das Auto reparieren zu müssen, um die Glühbirne zu wechseln, ist eine großartige Metapher, um Code an einer 12 Jahre alten Software zu schreiben, die Hunderttausende von Codezeilen hat, geschrieben von Menschen, die nicht miteinander gesprochen haben und ihre Änderungen nicht dokumentiert haben. Das Auto zu reparieren ist nicht oberste Priorität, bis es zum Erfordernis wird, die Hochprioritätslampe zu reparieren.

Ihr Triager-Job

Letztendlich wird nur ein erfahrener Entwickler in der Lage sein, Issues genau zu priorisieren. Aber Vernunft erfordert, dass ein erfahrener Entwickler für Dinge eingesetzt wird, die nur ein erfahrener Entwickler tun kann: einfachen Code schreiben, um technische Probleme effizient zu lösen, die eine gewisse Menge an Theorie und Design erfordern.

Der Kompromiss besteht darin, Triager dabei zu helfen, offensichtliche Issues zu priorisieren, damit sich Entwickler nur mit den weniger offensichtlichen Issues befassen und sich auf das Coding konzentrieren können.

1. Label nur Issues, die Sie verstehen und bei denen Sie sich beim Priorisieren wohl fühlen. Sie müssen nicht alle machen, es ist in Ordnung, wenn Sie es nicht wissen.
2. für Issues, die Sie verstehen:
   • Weisen Sie so weit wie möglich ein Prioritätslabel zu,
   • Weisen Sie so weit wie möglich ein Naturlabel zu,
   • Weisen Sie, wenn möglich, einen Meilenstein zu,
   • Schließen Sie das Issue sofort, wenn es ungültig oder ein Duplikat ist.
3. Für Issues, die Sie nicht verstehen:
   • Versuchen Sie, dem Autor mehr Fragen zu stellen,
   • Stellen Sie sicher, dass die Autoren alle relevanten Informationen liefern (Betriebssystem, Hardware, Schritte zur Reproduktion von Fehlern),
4. Es ist besser, wenn Sie nichts tun, als wenn Sie es falsch machen: Issues ohne Labels sind einfacher zu bemerken als Issues mit falschen Labels.
5. Scheuen Sie sich nicht, Video-Meetings einzuberufen: Besser ist es, sich 30 Minuten zusammenzusetzen, um ein produktives Gespräch zu führen und Entscheidungen anzupassen, als endlose Fäden nutzloser Nachrichten auszutauschen.

Danke!