Zgłaszanie nowego problemu

Sporządzenie dobrego zgłoszenia problemu lub błędu może mieć ogromny wpływ na możliwość rozwiązania problemu. Oto jak przesłać dobre zgłoszenie błędu do BeeWare.

Wyszukaj istniejące problemy

Przed zgłoszeniem nowego problemu przeszukaj indeks w poszukiwaniu istniejących problemów, które pasują do Twojego. Jeśli istnieje już otwarty problem, który wydaje się pasować do Twojego, dodaj komentarz do tego problemu, podając dodatkowe informacje na temat swoich doświadczeń. Na przykład, jeśli problem występuje w innej wersji języka Python lub innym systemie operacyjnym, te dodatkowe informacje mogą być pomocne w określeniu wpływu lub przyczyny problemu.

Jeśli znajdziesz zamkniętą sprawę, która wydaje się pasować do Twojego problemu, sprawdź, kiedy została ona zamknięta. Jeśli sprawa została zamknięta niedawno, prawdopodobnie oznacza to, że błąd został naprawiony i zostanie poprawiony w następnej wersji. Jeśli sprawa została zamknięta ponad 4 miesiące temu, prawdopodobnie problem, z którym się borykasz, jest inny — niezależnie od tego, jak podobny może wydawać się komunikat o błędzie.

Jeśli nie znajdziesz problemu, który odpowiada temu, co widzisz, warto zgłosić nowy problem.

Zacznij od dyskusji

Przed zgłoszeniem problemu na GitHubie warto najpierw zapytać w dyskusji, czy to, co się dzieje, to naprawdę błąd, czy może problem z konfiguracją lub procesem. Jeśli nie widzisz zachowania, które jest sprzeczne z tym, co jest w dokumentacji, warto zadać pytanie, zanim od razu zgłosisz błąd. Jeśli okaże się, że naprawdę znalazłeś problem, temat dyskusji można łatwo zamienić w zgłoszenie.

Rozpoczęcie dyskusji może również pomóc w upewnieniu się, że zgłaszasz problem w odpowiednim miejscu. Chociaż problem mógł wystąpić podczas korzystania z BeeWare, może on być spowodowany błędem w innym projekcie w ekosystemie BeeWare.

Pisanie dobrego raportu o błędzie

Jeśli zgłoszenie nowego problemu jest konieczne, ważne jest, aby podać jak najwięcej szczegółów. Dobry raport o błędzie zawiera wszystkie informacje potencjalnie związane z błędem, a także najmniejszy możliwy przykład pozwalający na odtworzenie błędu.

Przykład odtworzenia powinien być jak najkrótszy i jak najbardziej zwięzły, a jednocześnie powinien nadal wykazywać błąd. Podanie obszernego przykładu znacznie utrudnia rozwiązywanie problemów, zwłaszcza jeśli opiera się on na innych bibliotekach lub wymaga rozległej wiedzy na temat oczekiwanego zachowania lub wewnętrznej logiki przykładu.

Potrzebujemy jak najwięcej szczegółowych informacji. Obejmują one między innymi:

• Wersja systemu operacyjnego – aż do wersji mikro (na przykład macOS 15.7.2).
• Twoja wersja Pythona, również w wersji mikro (na przykład 3.14.1).
• W jaki sposób zainstalowałeś Python? Pobrałeś go ze strony python.org? Użyłeś Homebrew? uv? pyenv? conda? Coś innego?
• Konkretna wersja narzędzi BeeWare, z której korzystasz (na przykład Toga 0.5.3). Jeśli korzystasz z wersji rozwojowej, jakiego hasha Git używasz? Nie wystarczy powiedzieć „aktualna gałąź główna”, ponieważ może się ona zmieniać z dnia na dzień.
• Konkretne wersje innych pakietów, które muszą być zainstalowane, aby problem wystąpił. Możesz dołączyć wyniki uruchomienia python -m pip freeze w celu dostarczenia tych informacji.
• Jeśli plik dziennika został wygenerowany, to cały plik dziennika.
• Jeśli wygenerowano ślad stosu, należy podać cały ślad stosu. Nie wystarczy podać tylko końcowy komunikat o błędzie — ważny jest pełny kontekst śladu stosu. Najlepiej jest również podać go w formacie tekstowym, a nie jako zrzut ekranu.
• Wszelkie inne informacje dotyczące konfiguracji komputera lub sieci, które mogą mieć wpływ na ten problem. Czy komputer jest starszy lub wolniejszy? Czy jest to komputer służbowy, na którym zainstalowano zapory sieciowe, programy antywirusowe lub inne ograniczenia? Czy sieć działa wyjątkowo wolno? Czy system operacyjny działa z nietypowymi ustawieniami domyślnymi (takimi jak bardzo duża czcionka lub włączone inne technologie wspomagające)?

Spróbuj myśleć nieszablonowo i uwzględnij wszystko, co może mieć wpływ na problem, z którym się borykasz. Jeśli podasz nam więcej informacji niż potrzebujemy, z łatwością pominiemy te, które nie są nam potrzebne. Nie możemy wymyślić czegoś, czego nie podałeś.

Minimalny przykład

Najważniejszą częścią zgłoszenia błędu jest minimalny przypadek odtworzenia. Osoba trzecia powinna mieć możliwość przeczytania instrukcji dotyczących odtworzenia przypadku, postępowania zgodnie z nimi i zaobserwowania tego samego problemu. Może to oznaczać dostarczenie przykładowego projektu, w którym występuje problem — lub, jeszcze lepiej, wykorzystanie istniejącego już przykładu (takiego jak samouczek lub przykładowy projekt będący częścią istniejącej bazy kodu).

Twój pełny projekt nie jest minimalnym przypadkiem odtworzenia. Minimalny przypadek odtworzenia nie powinien zawierać żadnego kodu, który nie jest absolutnie niezbędny do odtworzenia problemu. Bądź bezwzględny podczas tworzenia przypadku odtworzenia — jeśli przycisk nie jest potrzebny do odtworzenia problemu, nie uwzględniaj go.

Często proces tworzenia takiego minimalnego przykładu pozwala znaleźć źródło problemu, bo zmuszasz się do dokładnego ustalenia, co jest przyczyną – czy to błąd w kodzie, czy może złe założenia albo nieprawidłowe użycie API.

Należy również wyraźnie opisać instrukcje dotyczące odtworzenia problemu. Stwierdzenie „Zamknij przykładową aplikację” może oznaczać kliknięcie przycisku zamykania okna, wybranie opcji „zamknij” z menu lub wpisanie kombinacji klawiszy Control-C w terminalu. Raport nie powinien pozostawiać żadnych wątpliwości co do czynności, które należy wykonać, aby odtworzyć problem.

Przesłanie raportu

Navigate to the project issues list, click the "New issue" button, and choose "Bug report" to begin the process.

Należy wypełnić wszystkie sekcje szablonu zgłoszenia. Szablon ten ma na celu pomóc Państwu w podaniu niezbędnych informacji. Proszę pamiętać, że zawsze mogą Państwo (i powinni!) podać więcej informacji niż wymaga tego szablon, ale minimalnym wymogiem jest podanie wszystkich informacji zawartych w szablonie.

W przypadku dołączania kodu, jeśli można go odtworzyć na podstawie istniejącego przykładu, takiego jak samouczek BeeWare, można podać link. W przeciwnym razie należy podać kod w raporcie. Powinien on być sformatowany w języku Markdown; blok kodu wymaga trzech znaków backtick (```) przed i po nim.

Jeśli chcesz dołączyć długi fragment tekstu, możesz go skrócić, używając następującej składni:

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

Po podaniu jak największej ilości informacji kliknij „Utwórz”, aby przesłać zgłoszenie.