Ein neues Problem melden¶

Das Verfassen eines guten Problem- oder Fehlerberichts kann den entscheidenden Unterschied bei der Fehlerbehebung ausmachen. Hier erfahren Sie, wie Sie einen guten Fehlerbericht bei BeeWare einreichen.

Suche nach vorhandenen Ausgaben¶

Bevor Sie ein neues Problem einreichen, suchen Sie im Index nach bestehenden Problemen, die Ihrem Problem entsprechen. Wenn es ein offenes Problem gibt, das zu Ihrem Problem zu passen scheint, fügen Sie einen Kommentar zu diesem Problem mit zusätzlichen Informationen über Ihre Erfahrungen hinzu. Wenn das Problem beispielsweise bei einer anderen Python-Version oder einem anderen Betriebssystem auftritt, können diese zusätzlichen Informationen hilfreich sein, um die Auswirkungen oder die Ursache des Problems zu ermitteln.

Wenn Sie ein geschlossenes Problem finden, das Ihrem Problem zu entsprechen scheint, prüfen Sie, wann dieses Problem geschlossen wurde. Wenn das Problem vor kurzem geschlossen wurde, bedeutet das wahrscheinlich, dass Ihr Fehler behoben wurde und in der nächsten Version behoben wird. Wenn das Problem vor mehr als 4 Monaten geschlossen wurde, ist es wahrscheinlich, dass es sich um ein anderes Problem handelt - egal wie ähnlich die Fehlermeldung auch sein mag.

Wenn Sie kein Problem finden, das Ihren Vorstellungen entspricht, sollten Sie ein neues Problem eröffnen.

Beginnen Sie mit einer Diskussion¶

Bevor Sie einen Fehler auf GitHub melden, sollten Sie mit einer Diskussion beginnen, um herauszufinden, ob es sich bei dem, was Sie erleben, tatsächlich um einen Fehler oder um ein Problem mit Ihrer Einrichtung oder Ihrem Prozess handelt. Wenn Sie nicht gerade ein Verhalten beobachten, das dem dokumentierten Verhalten direkt widerspricht, ist es wahrscheinlich sinnvoll, eine Frage zu stellen, bevor Sie direkt einen Fehlerbericht einreichen. Wenn sich herausstellt, dass Sie ein Problem gefunden haben, kann ein Diskussionsthema leicht in ein Problem umgewandelt werden.

Der Beginn einer Diskussion kann auch dazu beitragen, dass Sie ein Problem an der richtigen Stelle melden. Auch wenn Sie bei der Verwendung von BeeWare auf ein Problem gestoßen sind, kann das Problem durch einen Fehler in einem anderen Projekt im BeeWare-Ökosystem verursacht werden.

Einen guten Fehlerbericht schreiben¶

Wenn ein neues Problem erforderlich ist, ist es wichtig, so viele Details wie möglich anzugeben. Ein guter Fehlerbericht enthält alle Informationen, die mit dem Fehler in Verbindung stehen könnten, sowie ein möglichst kleines Beispiel für eine Reproduktion.

Das Reproduktionsbeispiel sollte so kurz und prägnant wie möglich sein und trotzdem den Fehler zeigen. Die Bereitstellung eines umfangreichen Beispiels erschwert die Fehlersuche erheblich, insbesondere wenn es auf andere Bibliotheken zurückgreift oder umfangreiche Kenntnisse über das erwartete Verhalten oder die interne Logik des Beispiels erfordert.

Wir brauchen so viele Details wie möglich. Dies beinhaltet, ist aber definitiv nicht beschränkt auf:

Die Version Ihres Betriebssystems - bis hin zur Mikroversion (z. B. macOS 15.7.2).
Ihre Python-Version, auch in der Mikro-Version (z. B. 3.14.1).
Wie haben Sie Python installiert? Haben Sie es von python.org heruntergeladen? Haben Sie Homebrew benutzt? uv? pyenv? conda? Etwas anderes?
Welche spezifische Version der BeeWare-Tools verwenden Sie (z. B. Toga 0.5.3). Wenn Sie eine Entwicklungsversion verwenden, welchen Git-Hash verwenden Sie? Es reicht nicht aus, "den aktuellen Hauptzweig" zu nennen, da sich dieser täglich ändern kann.
Die spezifischen Versionen anderer Pakete, die installiert sein müssen, um das Problem auszulösen. Sie können die Ergebnisse der Ausführung von python -m pip freeze einfügen, um diese Informationen bereitzustellen.
Wenn eine Protokolldatei erstellt wurde, die gesamte Protokolldatei.
Wenn ein Stacktrace erzeugt wurde, den gesamten Stacktrace. Geben Sie nicht nur die letzte Fehlermeldung an - der vollständige Kontext des Stacktrace ist wichtig. Es ist auch am besten, dies im Text-Format bereitzustellen, nicht als Bildschirmfoto.
Gibt es sonst noch etwas an Ihrem Computer oder Ihrer Netzwerkeinrichtung, das sich auf das Problem auswirken könnte? Ist Ihr Computer älter oder langsamer? Handelt es sich um einen Arbeitsplatzrechner, auf dem möglicherweise Firewalls, Virenschutzprogramme oder andere Einschränkungen installiert sind? Ist Ihr Netzwerk besonders langsam? Betreiben Sie Ihr Betriebssystem mit ungewöhnlichen Systemvorgaben (z. B. mit einer sehr großen Schriftart oder einer anderen aktivierten Hilfstechnologie)?

Versuchen Sie, über den Tellerrand hinauszuschauen und alles einzubeziehen, was Ihnen zu dem Problem einfällt, mit dem Sie konfrontiert sind. Wenn Sie uns mehr geben, als wir brauchen, können wir leicht ignorieren, was wir nicht brauchen. Wir können nicht mit etwas aufwarten, das Sie weggelassen haben.

Ein minimales Beispiel¶

Der wichtigste Teil eines Fehlerberichts ist ein minimaler Reproduktionsfall. Es sollte für eine dritte Partei möglich sein, die Anweisungen für Ihren Reproduktionsfall zu lesen, diese Anweisungen zu befolgen und das gleiche Problem zu beobachten. Das kann bedeuten, dass Sie ein Beispielprojekt zur Verfügung stellen, in dem das Problem auftritt - oder, noch besser, ein bereits existierendes Beispiel verwenden (z.B. ein Tutorial oder ein Beispielprojekt, das Teil der bestehenden Codebasis ist).

Ihr vollständiges Projekt ist kein minimaler Reproduktionsfall. Ein minimaler Reproduktionsfall sollte keinen Code enthalten, der nicht unbedingt erforderlich ist, um ein Problem zu lösen. Seien Sie rücksichtslos bei der Zusammenstellung Ihres Reproduktionsfalls - wenn eine Schaltfläche nicht benötigt wird, um das Problem zu lösen, lassen Sie diese Schaltfläche weg.

Oftmals wird durch die Entwicklung dieses minimalen Reproduktionsfalls die Ursache des Problems aufgedeckt, da Sie durch die Erstellung des minimalen Beispiels gezwungen sind, genau herauszufinden, was das Problem verursacht, ob es sich um einen Fehler im Code handelt oder ob es auf falsche Annahmen oder die Verwendung der API zurückzuführen ist.

Sie sollten auch explizit in allen Reproduktionsanweisungen sein. Wenn Sie sagen "Schließen Sie die Beispielanwendung", könnte das bedeuten, dass Sie auf die Schaltfläche "Schließen" im Fenster klicken, "Beenden" aus einem Menü wählen oder Control-C in einem Terminal eingeben. Ihr Bericht sollte keinen Raum für Unklarheiten darüber lassen, was getan werden muss, um das Problem zu reproduzieren.

Einreichung des Berichts¶

Navigieren Sie zur Projektproblemliste, klicken Sie auf die Schaltfläche „Neues Problem“ und wählen Sie „Fehlerbericht“, um den Vorgang zu starten.

Sie müssen alle Abschnitte der Vorlage ausfüllen. Wir stellen die Vorlage als Aufforderung zur Verfügung, damit Sie die erforderlichen Informationen bereitstellen können. Denken Sie daran, dass Sie immer mehr Informationen angeben können (und sollten!), als in der Vorlage verlangt werden, aber wir benötigen mindestens alle Informationen, die in der Vorlage enthalten sind.

Wenn Sie Code einfügen, können Sie einen Link angeben, falls Sie ihn mit einem vorhandenen Beispiel reproduzieren können, z. B. mit dem BeeWare-Tutorial. Andernfalls geben Sie den Code im Bericht an. Er sollte in Markdown formatiert sein; ein Codeblock benötigt drei Backticks (````) vor und nach dem Code.

Wenn Sie einen langen Textblock einfügen müssen, können Sie ihn mit der folgenden Syntax zu einem zusammengeklappten Inhalt machen:

<details>
<summary>Collapsed content title</summary>
Long block of text.
</details>

Sobald Sie so viele Informationen wie möglich eingegeben haben, klicken Sie auf "Erstellen", um den Bericht zu übermitteln.