Bug-Triage und Issue-Kuration#

Der Issue-Tracker ist wichtig für die Kommunikation im Projekt: er hilft Entwicklern, größere Projekte zu identifizieren, an denen sie arbeiten können, und Prioritäten zu diskutieren. Aus diesem Grund ist es wichtig, ihn zu kuratieren, Issues mit Labels zu versehen und nicht mehr notwendige Issues zu schließen.

Arbeiten an Issues, um sie zu verbessern#

Die Verbesserung von Issues erhöht ihre Chancen auf erfolgreiche Lösung. Richtlinien für das Einreichen guter Issues finden Sie hier. Dritte können nützliches Feedback geben oder sogar Kommentare zu einem Issue hinzufügen. Die folgenden Aktionen sind typischerweise nützlich

  • Dokumentieren von Issues, bei denen Elemente zur Reproduktion des Problems fehlen, wie z.B. Code-Beispiele

  • Vorschlagen einer besseren Verwendung der Code-Formatierung

  • Vorschlagen einer Umformulierung des Titels und der Beschreibung, um sie deutlicher auf das zu lösende Problem auszurichten

  • Verknüpfen mit verwandten Issues oder Diskussionen, während kurz beschrieben wird, wie sie zusammenhängen, z. B. "Siehe auch #xyz für einen ähnlichen Versuch" oder "Siehe auch #xyz, wo dasselbe bei SomeEstimator passiert ist" bietet Kontext und hilft der Diskussion.

Arbeiten an PRs zur Unterstützung der Überprüfung#

Das Überprüfen von Code wird ebenfalls gefördert. Mitwirkende und Benutzer sind eingeladen, am Überprüfungsprozess gemäß unseren Überprüfungsrichtlinien teilzunehmen.

Triage-Operationen für Mitglieder des Kernteams und des Teams für Mitwirkenden-Erfahrung#

Zusätzlich zu den oben genannten Punkten können Mitglieder des Kernteams und des Teams für Mitwirkenden-Erfahrung die folgenden wichtigen Aufgaben ausführen:

  • Aktualisieren von Labels für Issues und PRs: siehe die Liste der verfügbaren GitHub-Labels.

  • Feststellen, ob ein PR als "stalled" (verzögert) markiert werden muss oder Hilfe benötigt (dies ist typischerweise sehr wichtig im Kontext von Sprints, wo das Risiko besteht, viele unvollständige PRs zu erstellen)

  • Wenn ein verzögerter PR von einem neueren PR übernommen wird, dann markieren Sie den verzögerten PR als "Superseded" (abgelöst), hinterlassen Sie einen Kommentar auf dem verzögerten PR, der auf den neuen PR verlinkt, und schließen Sie den verzögerten PR wahrscheinlich.

  • Issues triagieren

    • Nutzungsfragen schließen und den Melder höflich darauf hinweisen, stattdessen Stack Overflow zu nutzen.

    • Doppelte Issues schließen, nachdem überprüft wurde, ob sie tatsächlich doppelt sind. Idealerweise verschiebt der ursprüngliche Einreicher die Diskussion zum älteren, doppelten Issue.

    • Nicht reproduzierbare Issues schließen, nachdem genügend Zeit (mindestens eine Woche) zum Hinzufügen zusätzlicher Informationen eingeräumt wurde.

Gespeicherte Antworten sind nützlich, um Zeit zu sparen und trotzdem einladend und höflich beim Triage zu sein.

Siehe die GitHub-Beschreibung für Rollen in der Organisation.

Ein typischer Workflow für die Triage von Issues#

Der folgende Workflow [1] ist ein guter Ansatz für die Triage von Issues:

  1. Dem Melder für das Eröffnen eines Issues danken

    Der Issue-Tracker ist für viele Menschen die erste Interaktion mit dem scikit-learn-Projekt selbst, über die reine Nutzung der Bibliothek hinaus. Daher möchten wir, dass es eine einladende, angenehme Erfahrung ist.

  2. Ist dies eine Nutzungsfrage? Wenn ja, schließen Sie sie mit einer höflichen Nachricht (hier ist ein Beispiel).

  3. Sind die notwendigen Informationen vorhanden?

    Wenn wichtige Informationen (wie die verwendete Version von scikit-learn) fehlen, fragen Sie gerne danach und versehen Sie das Issue mit dem Label "Needs info" (Benötigt Informationen).

  4. Ist dies ein doppeltes Issue?

    Wir haben viele offene Issues. Wenn ein neues Issue ein Duplikat zu sein scheint, verweisen Sie auf das ursprüngliche Issue. Wenn es ein klares Duplikat ist oder wenn Konsens besteht, dass es redundant ist, schließen Sie es. Bedanken Sie sich trotzdem beim Melder und ermutigen Sie ihn, sich am ursprünglichen Issue zu beteiligen und es vielleicht zu beheben.

    Wenn das neue Issue relevante Informationen liefert, wie z.B. ein besseres oder leicht abweichendes Beispiel, fügen Sie es dem ursprünglichen Issue als Kommentar oder als Bearbeitung des ursprünglichen Beitrags hinzu.

  5. Stellen Sie sicher, dass der Titel das Issue korrekt widerspiegelt. Wenn Sie die notwendigen Berechtigungen haben, bearbeiten Sie ihn selbst, wenn er nicht klar ist.

  6. Ist das Issue minimal und reproduzierbar?

    Für Fehlerberichte bitten wir den Melder, ein minimal reproduzierbares Beispiel bereitzustellen. Siehe diesen nützlichen Beitrag von Matthew Rocklin für eine gute Erklärung. Wenn das Beispiel nicht reproduzierbar ist oder eindeutig nicht minimal ist, fragen Sie den Melder gerne, ob er ein Beispiel bereitstellen oder das bereits vorhandene vereinfachen kann. Erkennen Sie an, dass das Schreiben minimal reproduzierbarer Beispiele harte Arbeit ist. Wenn der Melder Schwierigkeiten hat, können Sie versuchen, selbst eines zu schreiben.

    Wenn ein reproduzierbares Beispiel bereitgestellt wird, Sie aber eine Vereinfachung sehen, fügen Sie Ihr einfacheres reproduzierbares Beispiel hinzu.

  7. Fügen Sie die relevanten Labels hinzu, z.B. "Documentation" (Dokumentation), wenn das Issue sich auf die Dokumentation bezieht, "Bug" (Fehler), wenn es eindeutig ein Fehler ist, "Enhancement" (Erweiterung), wenn es sich um eine Erweiterungsanfrage handelt, ...

    Wenn das Issue klar definiert ist und die Behebung relativ unkompliziert erscheint, versehen Sie das Issue mit dem Label "Good first issue" (Gutes erstes Issue).

    Ein zusätzlicher nützlicher Schritt kann darin bestehen, das entsprechende Modul zu taggen, z.B. sklearn.linear_models, wenn relevant.

  8. Entfernen Sie das Label "Needs Triage" (Benötigt Triage) vom Issue, falls es vorhanden ist.