Zum Inhalt

Verwendung der Werkzeuge

Eine der wertvollsten Rückmeldungen, die wir erhalten können, ist die von Personen, die versuchen, die BeeWare-Tools zu nutzen, und dabei feststellen, dass es einen Reibungspunkt gibt oder eine Funktion fehlt. Es ist unglaublich nützlich für uns, alle Schwierigkeiten zu verstehen, die bei der Verwendung der Tools in der Praxis auftreten können.

Denken Sie an das, was Sie schon immer bauen wollten, und versuchen Sie es zu bauen. Wenn es Ihnen gelingt, Ihr Projekt zu bauen, herzlichen Glückwunsch! Du hast das, was du schon immer wolltest.

Wenn Sie jedoch keinen Erfolg haben, lassen Sie uns wissen, was schief gelaufen ist. Fehlte eine Funktion? Ist die Dokumentation in irgendeiner Hinsicht verwirrend oder lückenhaft? Wenn Sie uns Ihre Erfahrungen mitteilen, erhalten wir nützliche Einblicke, die wir in unseren Planungsprozess einfließen lassen können.

Wenn Sie auf Probleme stoßen, beginnen Sie ein neues Diskussionsthema, da es sich um den Beginn eines neuen Problems oder eines Funktionsvorschlags handeln könnte.

Verwendung von Hilfsmitteln

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.

Eine neue Funktion vorschlagen

Sie haben also eine Idee für eine Verbesserung für BeeWare - Wie können Sie diese Idee zur Prüfung einreichen?

Recherchieren Sie

Der erste Schritt besteht darin, den BeeWare issue tracker nach bestehenden feature issues (issues tagged "enhancement"), [documentation issues (issues tagged "documentation")] (https://github.com/search?q=org%3Abeeware+is%3Aopen+is%3Aissue+label%3Adocumentation&type=issues), oder Discussion threads um zu sehen, ob die Idee schon einmal vorgeschlagen wurde. Wenn dies der Fall ist und Sie neue Zusammenhänge oder Ideen hinzufügen möchten, fügen Sie diese in das bestehende Thema ein. Wenn Sie Hilfe bei Ihrer Recherche benötigen, können Sie im #dev-Kanal im BeeWare Discord nachfragen. Wir können Ihnen vielleicht Hinweise auf bestehende Threads geben, Ihnen einen Kontext liefern, der Ihnen nicht bekannt ist, oder Ihre Idee mit einer anderen Idee in Verbindung bringen, die auf den ersten Blick nicht verwandt ist.

Diskutieren Sie die Idee

Wenn Sie keine Hinweise auf Ihre Idee finden, starten Sie einen Diskussionsfaden. Beschreiben Sie in groben Zügen den Zweck und den Anwendungsfall für Ihre Idee. Machen Sie sich Gedanken darüber, wie die Funktion aussehen würde, wenn sie implementiert würde, z.B. die allgemeine Form einer API, das visuelle Erscheinungsbild einer Fähigkeit oder das Dokument, das hinzugefügt würde. Falls zutreffend, sollten Sie auch Untersuchungen darüber anstellen, wie Ihre Idee auf verschiedenen Plattformen aussehen würde.

Sobald der Diskussionsstrang eröffnet ist, werden das BeeWare-Team und der Rest der Community darauf reagieren. Das Kernteam wird sich bemühen, innerhalb von zwei Werktagen zumindest einen ersten Eindruck von Ihrer Idee zu vermitteln. Wenn eine Idee besonders komplex ist, kann eine detailliertere Analyse bis zu einer Woche dauern. Aufgrund von Ereignissen wie Feiertagen und Konferenzen kann sich diese Zeitspanne etwas verlängern.

Dies ist Ihre Gelegenheit, an einem Gespräch über Ihre Idee teilzunehmen. Wir können Sie um weitere Details oder Zusammenhänge bitten. Andere Mitglieder der Gemeinschaft können sich ebenfalls an der Diskussion beteiligen und andere Perspektiven, Vorschläge oder Gegenvorschläge einbringen. Das Ergebnis dieser Diskussion wird über die nächsten Schritte entscheiden.

Es ist wichtig zu verstehen, dass nicht alle Ideen akzeptiert werden. Der Grund, warum dieser Prozess mit einem Vorschlag beginnt, ist, dass Sie nicht die ganze Arbeit investieren müssen, nur um dann herauszufinden, dass es einen Grund gibt, warum Ihre Änderung nicht angenommen wird.

Das heißt aber nicht, dass es keine gute Idee war! Es kann technische Gründe dafür geben, dass sie nicht umgesetzt werden kann. Zum Beispiel könnten wir eine Idee ablehnen, wenn:

  • Es wäre schwierig oder unmöglich, sie auf allen unterstützten Plattformen zuverlässig zu implementieren; oder
  • Es wäre schwierig zu warten, oder die Wartung würde den Zugang zu einer Technologie oder Software erfordern, die nicht allgemein verfügbar ist; oder
  • Sie dient einem Nischenpublikum, bedeutet aber für andere Nutzer einen erheblichen Mehraufwand.

Wenn wir feststellen, dass Ihre Idee nicht passt, bedeutet das nicht unbedingt, dass Sie sie aufgeben sollten. Auch wenn wir eine bestimmte Idee ablehnen, können wir viel eher bereit sein, eine Plugin-Schnittstelle oder einen anderen Erweiterungspunkt hinzuzufügen, der es Ihnen ermöglicht, die gleiche Funktion als externe Bibliothek zu pflegen. Auf diese Weise können Sie die Funktion haben, ohne dass die spezifischen Wartungsprobleme oder Einschränkungen der Funktion zu einer Einschränkung für das Projekt selbst werden.

Umwandlung in einen formellen Antrag auf eine neue Funktion

Sobald die Diskussion einen Konsens über die Form eines Features erreicht hat, können Sie einen neuen [Feature Request issue] (https://github.com/beeware/beeware/issues/new/choose) im BeeWare issue tracker erstellen, der die Diskussion zusammenfasst und für den Kontext auf die Diskussion verweist.

Sie müssen Ihren Vorschlag für eine neue Funktion nicht selbst umsetzen; Sie können ein Problem mit den Details Ihres Vorschlags eröffnen. Allerdings bedeutet das bloße Veröffentlichen des Themas nicht, dass es für Sie implementiert werden wird. Sie müssen abwarten, bis es möglicherweise von jemand anderem aufgegriffen wird, der an der gleichen Funktion interessiert ist, sei es ein anderes Community-Mitglied oder das Kernteam; dies ist jedoch nicht garantiert. Wenn Sie die garantierte Implementierung wünschen, müssen Sie sie selbst implementieren oder jemanden bezahlen, der sie für Sie implementiert.