Odeslání nového problému¶

Sepsání dobré zprávy o problému nebo chybě může mít zásadní vliv na schopnost vyřešit daný problém. Zde je návod, jak odeslat dobrou zprávu o chybě na BeeWare.

Vyhledávání existujících problémů¶

Než odešlete nový problém, prohledejte index a najděte existující problémy, které odpovídají vašemu. Pokud existuje otevřený problém, který se zdá odpovídat vašemu problému, přidejte k němu komentář s dalšími informacemi o vaší zkušenosti. Pokud například problém pozorujete v jiné verzi Pythonu nebo v jiném operačním systému, mohou tyto další informace pomoci při určování dopadu nebo příčiny problému.

Pokud najdete uzavřený problém, který se zdá odpovídat vašemu problému, zkontrolujte, kdy byl tento problém uzavřen. Pokud byl problém uzavřen velmi nedávno, pravděpodobně to znamená, že vaše chyba byla opravena a bude napravena v příštím vydání. Pokud byl problém uzavřen před více než 4 měsíci, je pravděpodobné, že se jedná o jiný problém – bez ohledu na to, jak podobná se může zdát chybová zpráva.

Pokud nenajdete problém, který odpovídá tomu, co vidíte, může být vhodné otevřít nový problém.

Začněte diskusí¶

Než odešlete problém na GitHub, zvažte, zda nejprve nezačít diskusí, ve které se zeptáte, zda se skutečně jedná o chybu, nebo o problém s vaším nastavením či procesem. Pokud nezaznamenáte chování, které je v přímém rozporu s dokumentovaným chováním, pravděpodobně stojí za to se nejprve zeptat, než rovnou odešlete hlášení o chybě. Pokud se ukáže, že jste skutečně našli problém, lze téma diskuse snadno převést na problém.

Zahájení diskuze vám také pomůže ujistit se, že problém hlásíte na správném místě. I když jste se s problémem setkali při používání BeeWare, může být způsoben chybou v jiném projektu v ekosystému BeeWare.

Psaní dobré zprávy o chybě¶

Pokud je nutné nahlásit nový problém, je důležité poskytnout co nejvíce podrobností. Dobrá zpráva o chybě obsahuje všechny informace, které mohou souviset s danou chybou, a také co nejmenší příklad, jak chybu reprodukovat.

Příklad reprodukce by měl být co nejkratší a nejstručnější, ale zároveň by měl chybu jasně demonstrovat. Poskytnutí rozsáhlého příkladu značně ztěžuje řešení problému, zejména pokud je závislý na jiných knihovnách nebo vyžaduje rozsáhlé znalosti o očekávaném chování nebo vnitřní logice příkladu.

Potřebujeme co nejvíce podrobností, které nám můžete poskytnout. To zahrnuje mimo jiné:

Verze vašeho operačního systému – až po mikroverzi (například macOS 15.7.2).
Vaše verze Pythonu, včetně mikroverze (například 3.14.1).
Jak jste nainstalovali Python. Stáhli jste ho z python.org? Použili jste Homebrew? uv? pyenv? conda? Něco jiného?
Konkrétní verzi nástrojů BeeWare, kterou používáte (například Toga 0.5.3). Pokud používáte vývojovou verzi, jaký Git hash používáte? Nestačí říci „aktuální hlavní větev“, protože ta se může každý den měnit.
Konkrétní verze dalších balíčků, které musí být nainstalovány, aby se problém projevil. K poskytnutí těchto informací můžete přiložit výsledky spuštění python -m pip freeze.
Pokud byl vytvořen soubor protokolu, pak celý soubor protokolu.
Pokud byl vygenerován záznam o stavu zásobníku, uveďte celý záznam. Neuvádějte pouze konečnou chybovou zprávu – důležitý je celý kontext záznamu o stavu zásobníku. Nejlepší je uvést jej v textovém formátu, ne jako snímek obrazovky.
Jakékoli další informace o nastavení počítače nebo sítě, které mohou mít vliv na daný problém. Je váš počítač starší nebo pomalejší? Jedná se o pracovní počítač, který může mít nainstalované brány firewall, antivirové programy nebo jiná omezení? Je vaše síť obzvláště pomalá? Používáte operační systém s neobvyklými výchozími nastaveními (například velmi velkým písmem nebo jinými aktivními pomocnými technologiemi)?

Snažte se myslet mimo rámec a uveďte vše, co vás napadne a co by mohlo mít vliv na problém, se kterým se potýkáte. Pokud nám poskytnete více informací, než potřebujeme, můžeme snadno ignorovat to, co nepotřebujeme. Nemůžeme přijít s něčím, co jste opomněli uvést.

Minimální příklad¶

Nejdůležitější součástí hlášení chyby je minimální reprodukční případ. Třetí strana by měla být schopna přečíst si pokyny pro reprodukční případ, postupovat podle nich a pozorovat stejný problém. To může znamenat poskytnutí vzorového projektu, který problém demonstruje, nebo ještě lépe použití již existujícího příkladu (například tutoriálu nebo vzorového projektu, který je součástí stávající kódové základny).

Váš kompletní projekt není minimálním reprodukčním případem. Minimální reprodukční případ by neměl obsahovat žádný kód, který není nezbytně nutný k reprodukci problému. Při sestavování reprodukčního případu buďte nekompromisní – pokud k reprodukci problému není potřeba tlačítko, nezahrnujte ho.

Proces vývoje tohoto minimálního reprodukčního případu často odhalí zdroj problému, protože vytvoření minimálního příkladu vás nutí přesně zjistit, co je příčinou problému, ať už se jedná o chybu v kódu, nesprávné předpoklady nebo nesprávné použití API.

V pokynech k reprodukci byste měli být také výslovní. Výraz „Zavřete ukázkovou aplikaci“ může znamenat kliknutí na tlačítko zavření okna, výběr možnosti „ukončit“ z nabídky nebo zadání klávesové zkratky Control-C v terminálu. Vaše zpráva by neměla ponechávat žádný prostor pro nejednoznačnost ohledně toho, co je třeba udělat k reprodukci problému.

Odeslání zprávy¶

Přejděte na seznam problémů projektu, klikněte na tlačítko „Nový problém“ a vyberte možnost „Hlášení chyby“, abyste zahájili proces.

Musíte vyplnit všechny části šablony problému. Šablonu poskytujeme jako pomůcku, která vám pomůže zadat potřebné informace. Nezapomeňte, že můžete (a měli byste!) vždy zadat více informací, než šablona vyžaduje, ale minimálně potřebujeme všechny informace uvedené v šabloně.

Pokud vkládáte kód a můžete jej reprodukovat pomocí existujícího příkladu, jako je například tutoriál BeeWare, můžete uvést odkaz. V opačném případě uveďte kód v hlášení. Měl by být formátován pomocí Markdown; blok kódu musí být před a za ním označen třemi zpětnými lomítky (```).

Pokud potřebujete vložit dlouhý blok textu, můžete jej skrýt pomocí následující syntaxe:

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

Jakmile zadáte co nejvíce informací, klikněte na „Vytvořit“ a odešlete hlášení.