Používání nástrojů¶

Jednou z nejcennějších zpětných vazeb, které můžeme získat, jsou informace od lidí, kteří se snaží používat nástroje BeeWare a objeví v nich nějaké nedostatky nebo chybějící funkce. Je pro nás nesmírně užitečné pochopit všechny potíže, se kterými se můžete setkat při používání těchto nástrojů v praxi.

Vzpomeňte si na věc, kterou jste vždy chtěli vytvořit, a zkuste ji vytvořit. Pokud se ukáže, že jste schopni svůj projekt realizovat, gratulujeme! Máte to, co jste vždy chtěli.

Pokud však nebudete úspěšní, dejte nám vědět, co se pokazilo. Chyběla nějaká funkce? Je dokumentace matoucí nebo v něčem nedostatečná? Sdílení vašich zkušeností nám poskytuje užitečné informace, které můžeme využít při plánování.

Pokud narazíte na nějaké problémy, založte nové diskusní téma, protože by se mohlo jednat o začátek nového problému nebo návrhu nové funkce.

Používání nástrojů pro přispívání¶

Odeslat nový problém

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í.

Navrhnout novou funkci

Máte tedy nápad, jak vylepšit BeeWare – jak tento nápad předložit k posouzení?

Proveďte průzkum¶

Prvním krokem je prohledat systém pro sledování problémů BeeWare a najít existující problémy s funkcemi (problémy označené „vylepšení”), problémy s dokumentací (problémy označené „dokumentace”), nebo diskusní vlákna, abyste zjistili, zda již někdo tento nápad nenavrhl. Pokud ano a máte nové souvislosti nebo nápady, které chcete přidat, zahrňte je do existujícího vlákna. Pokud potřebujete pomoc s výzkumem, můžete se zeptat v kanálu #dev na BeeWare Discord. Možná vám budeme moci ukázat směr existujících vláken, poskytnout souvislosti, o kterých možná nevíte, nebo propojit váš nápad s jiným nápadem, který se na první pohled nemusí zdát související.

Diskutujte o této myšlence¶

Pokud nenajdete žádné existující odkazy na svůj nápad, založte diskusní vlákno. Uveďte obecný popis účelu a použití svého nápadu. Uveďte také své představy o tom, jak by daná funkce vypadala, pokud by byla implementována, například obecný tvar API, vizuální podoba funkce nebo dokument, který by byl přidán. Pokud je to relevantní, uveďte také veškerý výzkum, který jste provedli ohledně toho, jak by se váš nápad projevil na různých platformách.

Jakmile bude diskusní vlákno otevřeno, tým BeeWare a zbytek komunity na něj zareagují. Jádro týmu se bude snažit poskytnout alespoň první dojem z vašeho nápadu do dvou pracovních dnů. Pokud je nápad obzvláště složitý, může podrobnější analýza trvat až týden. Události jako svátky a konference mohou tyto lhůty mírně prodloužit.

Toto je vaše příležitost zapojit se do diskuse o vašem nápadu. Můžeme vás požádat o další podrobnosti nebo kontext. Do diskuse se mohou zapojit i další členové komunity, kteří mohou přinést jiné pohledy, návrhy nebo protinávrhy. Výsledek této diskuse určí další kroky.

Je důležité si uvědomit, že ne všechny nápady budou přijaty. Důvodem, proč tento proces začíná návrhem, je zabránit tomu, abyste vynaložili veškeré úsilí, jen abyste zjistili, že existuje důvod, proč vaše změna nebude přijata.

To ale neznamená, že to nebyl dobrý nápad! Může existovat technické důvody, proč jej nelze realizovat. Například můžeme nápad zamítnout, pokud:

Bylo by obtížné nebo nemožné jej spolehlivě implementovat na všech podporovaných platformách; nebo
Bylo by obtížné jej udržovat nebo by údržba vyžadovala přístup k technologii nebo softwaru, který není široce dostupný; nebo
Slouží úzké skupině uživatelů, ale ostatním uživatelům způsobuje značné náklady.

Pokud usoudíme, že váš nápad není vhodný, nemusí to nutně znamenat, že byste ho měli vzdát. I když můžeme odmítnout konkrétní nápad, můžeme být mnohem vstřícnější k přidání rozhraní pluginu nebo jiného rozšíření, které by vám umožnilo zachovat stejnou funkci jako externí knihovna. Tímto způsobem můžete mít danou funkci, ale bez konkrétních problémů s údržbou nebo omezeními, která by se stala překážkou pro samotný projekt.

Převést na formální požadavek na funkci¶

Jakmile se v diskusi dosáhne shody ohledně podoby funkce, můžete v systému pro sledování problémů beeware vytvořit nový požadavek na funkci, který shrne diskusi a bude obsahovat odkaz na diskusi pro kontext.

Nemusíte svůj návrh funkce implementovat sami; můžete otevřít issue s podrobnostmi o tom, co navrhujete. Pouhé zveřejnění issue však neznamená, že bude pro vás implementováno. Budete muset počkat, až se ho ujme někdo jiný, kdo má o stejnou funkci zájem, ať už se jedná o jiného člena komunity nebo členy hlavního týmu; není však zaručeno, že se tak stane. Pokud chcete mít jistotu, že bude funkce implementována, budete ji muset implementovat sami nebo zaplatit někoho, kdo to udělá za vás.