Przejdź do treści

Korzystanie z narzędzi

Jedną z najcenniejszych informacji zwrotnych, jakie możemy uzyskać, są opinie osób próbujących korzystać z narzędzi BeeWare i odkrywających pewne niedociągnięcia lub brakujące funkcje. Niezwykle przydatne jest dla nas zrozumienie wszelkich trudności, jakie mogą Państwo napotkać podczas korzystania z tych narzędzi w praktyce.

Pomyśl o rzeczy, którą zawsze chciałeś zbudować, i spróbuj ją zbudować. Jeśli okaże się, że jesteś w stanie zrealizować swój projekt, gratulacje! Masz to, czego zawsze pragnąłeś.

Jeśli jednak nie udało Ci się, daj nam znać, co poszło nie tak. Czy brakowało jakiejś funkcji? Czy dokumentacja jest niejasna lub niekompletna? Dzielenie się swoimi doświadczeniami daje nam cenne informacje, które możemy wykorzystać do kształtowania naszego procesu planowania.

Jeśli napotkasz jakiekolwiek problemy, utwórz nowy temat dyskusji, ponieważ może to być początek nowego problemu lub propozycji funkcji.

Wykorzystanie narzędzi współtworzenia

Zgłoś nową sprawę

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.

Zaproponuj nową funkcję

Masz pomysł na ulepszenie BeeWare – jak zgłosić ten pomysł do rozpatrzenia?

Zrób swoje badania

Pierwszym krokiem jest przeszukanie systemu śledzenia problemów BeeWare pod kątem istniejących problemów dotyczących funkcji (problemy oznaczone tagiem „enhancement”), problemów dotyczących dokumentacji (problemy oznaczone tagiem „documentation”) lub wątków dyskusyjnych, aby sprawdzić, czy pomysł został już wcześniej zgłoszony. Jeśli tak, a masz nowe informacje lub pomysły do dodania, dołącz je do istniejącego wątku. Jeśli potrzebujesz pomocy w poszukiwaniach, możesz poprosić o nią na kanale #dev na BeeWare Discord. Być może będziemy w stanie wskazać Ci istniejące wątki, dostarczyć informacji, których możesz nie znać, lub połączyć Twój pomysł z innym, który na pierwszy rzut oka może wydawać się niepowiązany.

Omów pomysł

Jeśli nie znajdziesz żadnych istniejących odniesień do swojego pomysłu, rozpocznij wątek dyskusji. Przedstaw ogólny opis celu i zastosowania swojego pomysłu. Dodaj wszelkie przemyślenia na temat tego, jak wyglądałaby ta funkcja, gdyby została wdrożona, np. ogólny kształt interfejsu API, wygląd wizualny funkcji lub dokument, który zostałby dodany. W stosownych przypadkach należy również dołączyć wszelkie badania dotyczące tego, jak pomysł zostałby zrealizowany na różnych platformach.

Po otwarciu wątku dyskusji zespół BeeWare i reszta społeczności udzielą odpowiedzi. Główny zespół postara się przedstawić przynajmniej wstępną opinię na temat Twojego pomysłu w ciągu dwóch dni roboczych. Jeśli pomysł jest szczególnie złożony, bardziej szczegółowa analiza może potrwać do tygodnia. Wydarzenia takie jak święta i konferencje mogą spowodować nieznaczne wydłużenie tych terminów.

To Twoja szansa, aby wziąć udział w dyskusji na temat Twojego pomysłu. Możemy poprosić Cię o podanie dodatkowych szczegółów lub kontekstu. Inni członkowie społeczności również mogą włączyć się do dyskusji, przedstawiając inne perspektywy, sugestie lub kontrpropozycje. Wynik tej dyskusji będzie decydował o kolejnych krokach.

Ważne jest, aby zrozumieć, że nie wszystkie pomysły zostaną zaakceptowane. Proces ten rozpoczyna się od złożenia wniosku, aby uniknąć sytuacji, w której wykonasz całą pracę, a następnie dowiesz się, że istnieje powód, dla którego Twoja zmiana nie zostanie zaakceptowana.

Nie oznacza to, że nie był to dobry pomysł! Mogą istnieć techniczne powody, dla których nie można go wdrożyć. Na przykład możemy odrzucić pomysł, jeśli:

  • Byłoby to trudne lub niemożliwe do wdrożenia w sposób niezawodny na wszystkich obsługiwanych platformach; lub
  • Byłoby to trudne do utrzymania lub konserwacja wymagałaby dostępu do technologii lub oprogramowania, które nie są powszechnie dostępne; lub
  • Obsługuje niszową grupę odbiorców, ale nakłada znaczne obciążenia na innych użytkowników.

Jeśli uznamy, że Twój pomysł nie pasuje, nie oznacza to koniecznie, że powinieneś z niego zrezygnować. Chociaż możemy odrzucić konkretny pomysł, możemy być znacznie bardziej skłonni do dodania interfejsu wtyczki lub innego punktu rozszerzenia, który pozwoliłby Ci zachować tę samą funkcję jako bibliotekę zewnętrzną. W ten sposób możesz mieć tę funkcję, ale bez konkretnych problemów związanych z utrzymaniem lub ograniczeń funkcji, które stałyby się ograniczeniem dla samego projektu.

Przekształć w formalną prośbę o dodanie funkcji

Gdy dyskusja doprowadzi do konsensusu w sprawie formy funkcji, można utworzyć nowe zgłoszenie dotyczące funkcji (https://github.com/beeware/beeware/issues/new/choose) w systemie śledzenia zgłoszeń BeeWare, które podsumowuje dyskusję i zawiera link do niej dla kontekstu.

Nie musisz samodzielnie wdrażać swojej propozycji funkcji; możesz zgłosić problem, podając szczegóły swojej propozycji. Jednak samo zgłoszenie problemu nie oznacza, że zostanie on wdrożony. Musisz poczekać, aż ktoś inny zainteresowany tą samą funkcją, czy to inny członek społeczności, czy zespół główny, potencjalnie ją wybierze; nie ma jednak gwarancji, że tak się stanie. Jeśli chcesz mieć gwarancję wdrożenia, musisz wdrożyć ją samodzielnie lub zapłacić komuś, kto zrobi to za Ciebie.