Oprava problému

BeeWare sleduje seznam známých problémů. Jakýkoli z těchto problémů je kandidátem na řešení.

Tento seznam lze filtrovat různými způsoby. Můžete například filtrovat podle platformy, abyste se mohli soustředit na problémy, které se týkají platforem, na kterých můžete testovat, nebo můžete filtrovat podle typu problému, například chyby v dokumentaci. K dispozici je také filtr pro dobré první problémy – jedná se o problémy, které byly identifikovány jako problémy se známou příčinou a domníváme se, že jejich oprava by měla být relativně jednoduchá (i když se v naší analýze můžeme mýlit).

Pokud je problém starší než 6 měsíců, je zcela možné, že již byl vyřešen, takže prvním krokem je ověřit, zda lze problém reprodukovat. Použijte informace uvedené v hlášení o chybě a zkuste problém reprodukovat. Pokud problém nelze reprodukovat, nahlaste své zjištění jako komentář k problému a vyberte si jiný problém.

Pokud se vám podaří problém reprodukovat, zkuste jej opravit! Zjistěte, jaká kombinace kódu implementuje danou funkci, a zkuste přijít na to, co nefunguje správně.

I když problém nedokážete vyřešit, stojí za to nahlásit vše, co během procesu zjistíte, jako komentář k danému problému. Pokud najdete zdroj problému, ale neřešení, tato informace často postačí někomu, kdo se v dané platformě vyzná lépe, aby problém vyřešil. Pokud problém ještě neobsahuje dobrý reprodukční případ (malou ukázkovou aplikaci, která nedělá nic jiného než reprodukuje problém), může být jeho poskytnutí velkou pomocí.

Přispění opravou problému

Nastavení vývojového prostředí

Příspěvky do BeeWare vyžadují nastavení vývojového prostředí.

Předpoklady

Budete muset nainstalovat následující předpoklady.

macOSLinuxWindows

BeeWare vyžaduje Python 3.10+. Budete také potřebovat metodu pro správu virtuálních prostředí (například venv).

Verzi nainstalovaného Pythonu můžete ověřit spuštěním:

Python 3.8.10 (výchozí, 20. července 2020, 16:16:00)

Pokud máte nainstalováno více než jednu verzi Pythonu, možná budete muset nahradit python3 konkrétním číslem verze (např. python3.13)

Doporučujeme se vyhnout nedávno vydané verzi Pythonu (tj. verzím, které mají mikroverzi „.0“ nebo „.1“, jako např. 3.14.0). Důvodem je to, že nástroje potřebné pro podporu Pythonu na macOS často zaostávají a obvykle nejsou k dispozici pro nedávno vydané stabilní verze Pythonu.

BeeWare vyžaduje Python 3.10+. Budete také potřebovat metodu pro správu virtuálních prostředí (například venv).

Verzi nainstalovaného Pythonu můžete ověřit spuštěním:

Python 3.8.10 (výchozí, 20. července 2020, 16:16:00)

Pokud máte nainstalováno více než jednu verzi Pythonu, možná budete muset nahradit python3 konkrétním číslem verze (např. python3.13)

Doporučujeme se vyhnout nedávno vydané verzi Pythonu (tj. verzím, které mají mikroverzi „.0“ nebo „.1“, jako např. 3.14.0). Důvodem je to, že nástroje potřebné pro podporu Pythonu v systému Linux často zaostávají a obvykle nejsou k dispozici pro nedávno vydané stabilní verze Pythonu.

BeeWare vyžaduje Python 3.10+. Budete také potřebovat metodu pro správu virtuálních prostředí (například venv).

Verzi nainstalovaného Pythonu můžete ověřit spuštěním:

C:\...>py -3 --version

Pokud máte nainstalováno více než jednu verzi Pythonu, možná budete muset nahradit -3 konkrétním číslem verze (např. -python3.13)

Doporučujeme se vyhnout nedávno vydané verzi Pythonu (tj. verzím, které mají mikroverzi „.0“ nebo „.1“, jako např. 3.14.0). Důvodem je to, že nástroje potřebné pro podporu Pythonu ve Windows často zaostávají a obvykle nejsou k dispozici pro nedávno vydané stabilní verze Pythonu.

Nastavte si vývojové prostředí

Doporučeným způsobem nastavení vývojového prostředí pro BeeWare je použití virtuálního prostředí, a následná instalace vývojové verze BeeWare a jejích závislostí.

Klonujte repozitář BeeWare

Dále přejděte na stránku BeeWare na GitHubu, a pokud jste tak ještě neučinili, forkněte repozitář do svého vlastního účtu. Poté klikněte na tlačítko „<> Code“ ve vašem forku. Pokud máte v počítači nainstalovanou desktopovou aplikaci GitHub, můžete vybrat možnost „Open with GitHub Desktop“ (Otevřít v GitHub Desktop); v opačném případě zkopírujte uvedenou adresu HTTPS URL a použijte ji ke klonování repozitáře do svého počítače pomocí příkazového řádku:

macOSLinuxWindows

Rozdělte repozitář BeeWare a poté:

$ git clone https://github.com/<vaše uživatelské jméno>/beeware.git

(nahraďte svým uživatelským jménem na GitHubu)

Rozdělte repozitář BeeWare a poté:

$ git clone https://github.com/<vaše uživatelské jméno>/beeware.git

(nahraďte svým uživatelským jménem na GitHubu)

Rozdělte repozitář BeeWare a poté:

C:\...>git clone https://github.com/<vaše uživatelské jméno>/beeware.git

(nahraďte svým uživatelským jménem na GitHubu)

Nastavit upstream repozitář

Po naklonování vaší větve přidejte repozitář BeeWare jako vzdálený repozitář upstream. Tím získá váš lokální klon odkaz na původní repozitář, což usnadní synchronizaci aktualizací v průběhu času.

Budete také potřebovat tagy z upstream, aby nástroje jako Toga a Briefcase mohly určit přesná čísla verzí:

macOSLinuxWindows

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

C:\...>git remote add upstream https://github.com/beeware/beeware.git
C:\...>git fetch --tags upstream

Pokud chcete, aby vaše vidlice také obsahovala tyto tagy, můžete je odeslat:

$ git push --tags

To může být užitečné, pokud později vytvoříte nový klon a chcete, aby byly tagy dostupné z vašeho forku.

Vytvořte virtuální prostředí

Chcete-li nastavit virtuální prostředí a upgradovat pip, spusťte:

macOSLinuxWindows

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

C:\...>cd beeware
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip

Vaše výzva by nyní měla mít před sebou předponu (.venv).

Nainstalovat BeeWare

Nyní, když máte zdrojový kód, můžete provést editovatelnou instalaci BeeWare do svého vývojového prostředí. Spusťte následující příkaz:

macOSLinuxWindows

(.venv) $ python -m pip install -U -e . --group dev

(.venv) $ python -m pip install -U -e . --group dev

(.venv) C:\...>python -m pip install -U -e . --group dev

Povolit předběžné potvrzení

BeeWare používá nástroj nazvaný pre-commit, který identifikuje jednoduché problémy a standardizuje formátování kódu. Toho dosahuje instalací git hooku, který automaticky spustí sérii linterů kódu před finalizací jakéhokoli git commitu. Chcete-li povolit pre-commit, spusťte:

macOSLinuxWindows

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit

Nyní jste připraveni začít hackovat BeeWare!

Práce z pobočky

Než začnete pracovat na změně, ujistěte se, že jste vytvořili větev. Ve výchozím nastavení se při klonování vidlice repozitáře dostanete do větve main. Jedná se o přímou kopii větve BeeWare .

I když můžete odeslat žádost o stažení z vaší větve main, je lepší, když to nebudete dělat. Pokud odešlete žádost o stažení, která je téměř správná, člen jádrového týmu, který vaši žádost o stažení posuzuje, může provést potřebné změny, místo aby vám poskytl zpětnou vazbu s žádostí o drobnou změnu. Pokud však odešlete žádost o stažení z vaší větve main, recenzenti nebudou moci provádět úpravy.

Práce na hlavní větvi také ztěžuje práci vám po dokončení prvního požadavku na stažení. Pokud chcete pracovat na druhém požadavku na stažení, budete potřebovat „čistou“ kopii hlavní větve upstreamového projektu, na které budete moci založit svůj druhý příspěvek; pokud jste svůj první příspěvek vytvořili z větve main, již nemáte k dispozici tuto čistou verzi.

Místo toho byste měli provádět změny na funkční větvi. Funkční větev má jednoduchý název, který identifikuje změnu, kterou jste provedli. Pokud například opravujete chybu, která způsobuje problémy s kompilací ve Windows 11, můžete vytvořit feature branch fix-win11-build. Pokud se vaše chyba týká konkrétního nahlášeného problému, je také běžné odkazovat na číslo tohoto problému v názvu větve (např. fix-1234).

Chcete-li vytvořit větev funkcí fix-win11-build, spusťte:

macOSLinuxWindows

(.venv) $ git switch -c fix-win11-build

(.venv) $ git switch -c fix-win11-build

(.venv) C:\...>git switch -c fix-win11-build

Reprodukujte problém

Problém nelze vyřešit, pokud ho vůbec nemáte. Proto je reprodukce problému nezbytným předpokladem pro jeho vyřešení. V softwaru se problémy běžně označují jako „chyby“ (https://en.wikipedia.org/wiki/Software_bug) a problémy se často nazývají „hlášení o chybách“.

Někdo nahlásil chybu. Musíte ověřit, zda kroky popsané v hlášení vedou k nahlášené chybě. Můžete dosáhnout stejného výsledku, pokud provedete přesně to, co je popsáno v hlášení? Pokud ne, musíte zjistit proč.

Chyby v kódu

V ideálním případě budete mít stejné nastavení jako osoba, která chybu nahlásila, budete postupovat podle pokynů a budete schopni chybu reprodukovat tak, jak je popsáno. V mnoha případech to však nebude tak jednoduché. Mnoho hlášení chyb obsahuje pouze vágní vysvětlení a vágní sadu podmínek. Problémem je, že mnoho chyb se liší v závislosti na sadě podmínek, včetně toho, jak s nimi uživatel pracuje, různých předpokladů, operačního systému, verze operačního systému, architektury CPU nebo toho, zda je počítač uživatele starý a pomalý, nebo nový a rychlý. Čím více informací o situaci kolem chyby máme, tím lépe. Zkuste reprodukovat podmínky, které uvedl autor hlášení. Pokud se vám to nepodaří, dalším krokem může být vyžádání dalších informací od osoby, která chybu nahlásila.

Nejlepší způsob, jak reprodukovat chybu, je použít co nejmenší příklad, který stále vykazuje daný problém. Většinou uživatelé neposkytují minimální funkční příklad; pokud poskytnou jakýkoli příklad, bude přímo zkopírován z jejich „reálné“ aplikace. Vaším cílem bude zredukovat hlášení na nejjednodušší možnou formu, která problém projeví. Nejlepším případem reprodukce je co nejmenší program. Tato redukce je sama o sobě užitečná, protože určuje, v čem spočívá skutečný problém. Kdokoli může vzít minimální příklad, spustit ho a pozorovat popsanou chybu.

Chyby v dokumentaci

Chyby v dokumentaci se mohou projevovat různými způsoby. Mohou se vyskytnout problémy s formátováním, které vedou k problémům se zobrazením. Někdy se ani nejedná o chybu; osoba mohla dokumentaci špatně přečíst nebo udělala opravdovou chybu. To nutně neznamená, že s dokumentací není žádný problém. Obsah může být nejasný nebo nepřesný, což vede k záměně nebo nesprávnému výkladu. Je možné, že koncept, který by měl být projednán, není, protože není vůbec zdokumentován.

Když je nahlášena chyba týkající se dokumentace, je třeba ověřit, zda nahlášený problém skutečně stále existuje. V případě problémů s vykreslováním je třeba sestavit dokumentaci a zkontrolovat, zda se problém dá reprodukovat. Problémy s obsahem je třeba ověřit přečtením, aby se zjistilo, zda nikdo neodeslal aktualizaci.

Aktualizujte problém

Posledním krokem v procesu třídění je zdokumentování vašich zjištění prostřednictvím komentáře k danému problému.

Pokud jste schopni problém přesně reprodukovat tak, jak je popsán, stačí to uvést. Zanechte komentář, ve kterém uvedete, že jste potvrdili, že se u vás vyskytuje stejný problém, přesně tak, jak jej popsal původní autor hlášení.

Pokud jste schopni poskytnout další souvislosti, uveďte podrobnosti o těchto souvislostech. Může se jednat například o možnost reprodukovat problém na jiném operačním systému nebo s jinou verzí některého z použitých softwarů, případně o jakékoli jiné odlišnosti od původní zprávy.

Pokud v původní zprávě chyběly podrobnosti potřebné k reprodukci problému, uveďte tyto podrobnosti. Může se jednat například o údaje o operačním systému nebo verzi, které v původní zprávě nebyly uvedeny, úplnější protokoly nebo záznamy o stavu paměti, případně jasnější pokyny k přesnému postupu potřebnému k reprodukci problému. Pokud jste vyvinuli jednodušší způsob reprodukce problému (nebo původní autor zprávy neposkytl případ reprodukce), můžete uvést podrobnosti o této metodice reprodukce.

Pokud problém nelze reprodukovat, zanechte také komentář s podrobným popisem toho, co jste zkusili. Vědět, kde problém neexistuje, je téměř stejně důležité jako vědět, kde existuje, protože to pomáhá zúžit možné příčiny. Pokud máte nějaké teorie o tom, proč se vám nedaří problém reprodukovat – například pokud si myslíte, že se jedná o chybu v používání nebo že problém byl vyřešen nedávnou aktualizací operačního systému – uveďte tuto spekulaci jako součást svého komentáře.

Nakonec můžete jádrovému týmu poskytnout jakékoli doporučení, které máte. Pokud se domníváte, že původní zpráva obsahuje chybu, navrhněte, aby byla záležitost uzavřena; pokud máte teorii o příčině problému, můžete ji také navrhnout. Vaše komentáře pomohou jádrovému týmu vyřešit, jak postoupit záležitost do další fáze.

Pokud řešení problému vyžaduje změny v kódu:

Psát, spouštět a testovat kód

Oprava chyby nebo implementace nové funkce bude vyžadovat, abyste napsali nový kód.

Máme příručku pro psaní kódu, která obsahuje pokyny pro psaní kódu pro BeeWare.

Vývoj řízený testy

Dobrým způsobem, jak zajistit, že váš kód bude fungovat podle vašich představ, je nejprve napsat testovací případ, který to ověří. Tento testovací případ by měl zpočátku selhat, protože kód, který má otestovat, ještě neexistuje. Poté můžete provést změny v kódu potřebné k tomu, aby test proběhl úspěšně, a mít jistotu, že to, co jste napsali, řeší problém tak, jak jste očekávali.

Spusťte svůj kód

Jakmile kód napíšete, musíte se ujistit, že funguje. Budete jej muset spustit ručně, abyste ověřili, zda dělá to, co očekáváte. Pokud jste tak ještě neučinili, měli byste pro své změny napsat testovací případ; jak již bylo zmíněno výše, tento test by měl selhat, pokud je váš kód zakomentován nebo chybí.

Svůj testovací případ přidáte do testovací sady, aby mohl být spuštěn společně s ostatními testy. Dalším krokem je spuštění testovací sady.

Spuštění testů a pokrytí

BeeWare využívá tox ke správě testovacího procesu a pytest pro svou vlastní sadu testů.

Výchozí příkaz tox zahrnuje spuštění:

• háčky před potvrzením
• towncrier kontrola poznámek k verzi

• kontrola dokumentace

• sada testů pro dostupné verze jazyka Python

• zprávy o pokrytí kódu

To je v podstatě to, co spustí CI, když odešlete žádost o začlenění.

Chcete-li spustit celou sadu testů, zadejte:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

(.venv) C:\...>tox

Spuštění celé testovací sady může chvíli trvat. Můžete jej výrazně urychlit spuštěním tox paralelně, a to pomocí příkazu tox p (nebo tox run-parallel). Při paralelním spuštění testovací sady budete dostávat méně informací o jejím průběhu, ale na konci testování se vám i tak zobrazí souhrn všech zjištěných problémů. Měl by se zobrazit výpis potvrzující, že testy proběhly. Můžete vidět SKIPPED testů, ale nikdy byste neměli dostat žádné výsledky testů FAIL nebo ERROR. Před sloučením každé opravy spouštíme naši kompletní sadu testů. Pokud tento proces odhalí nějaké problémy, opravu nesloučíme. Pokud narazíte na chybu nebo selhání testu, buď je ve vašem testovacím prostředí něco v nepořádku, nebo jste narazili na okrajový případ, který jsme dosud nezaznamenali – v každém případě nám to dejte vědět!

Kromě úspěšného absolvování testů by mělo být vykazováno 100% pokrytí testy.

Spouštění různých variant testů

Spustit testy pro více verzí jazyka Python

Ve výchozím nastavení se mnoho příkazů tox pokusí spustit sadu testů několikrát, a to jednou pro každou verzi jazyka Python, kterou BeeWare podporuje. K tomu je však nutné, aby byly všechny tyto verze jazyka Python nainstalovány ve vašem počítači a byly dostupné pro proces [vyhledávání]tox jazyka Python v (https://virtualenv.pypa.io/en/latest/explanation.html#python-discovery). Obecně platí, že pokud je nějaká verze jazyka Python dostupná prostřednictvím PATH, měl by ji tox dokázat najít a použít.

Spustit pouze sadu testů

Pokud na nové funkci pracujete v rychlém cyklu, nemusíte spouštět celou sadu testů; stačí spustit pouze jednotkové testy. K tomu zadejte:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

(.venv) C:\...>tox -e py

Spustit podmnožinu testů

Ve výchozím nastavení příkaz tox spustí všechny testy v sadě jednotkových testů. Při vývoji nového testu může být užitečné spustit pouze tento jeden test. K tomu můžete jako argument příkazu pytest předat [libovolný specifikátor (https://docs.pytest.org/en/latest/how-to/usage.html#specifying-which-tests-to-run)]tox. Tyto cesty k testům jsou relativní vůči adresáři briefcase. Chcete-li například spustit pouze testy v jednom souboru, zadejte:

macOSLinuxWindows

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py

I při spuštění pouze části testovací sady obdržíte zprávu o pokrytí – výsledky pokrytí však budou zahrnovat pouze řádky kódu, které byly provedeny konkrétními testy, které jste spustili.

Spustit sadu testů pro konkrétní verzi jazyka Python

Ve výchozím nastavení se tox -e py spustí pomocí interpretu, který se na vašem počítači přiřazuje k python. Pokud máte nainstalováno více verzí jazyka Python a chcete otestovat konkrétní verzi z těch, které máte nainstalované, můžete určit konkrétní verzi jazyka Python, která se má použít. Chcete-li například spustit sadu testů v jazyce Python 3.10, zadejte:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

(.venv) C:\...>tox -e py310

Podskupinu testů [test-subset] lze spustit tak, že do příkazového řádku přidáte -- a specifikaci testu.

Spustit sadu testů bez měření pokrytí (rychle)

Ve výchozím nastavení spustí tox sadu testů v jednovláknovém režimu. Spuštěním sady testů paralelně můžete její provedení zrychlit. V tomto režimu se nevytvářejí soubory s pokrytím, a to kvůli složitosti zaznamenávání pokrytí v rámci spuštěných procesů. Chcete-li spustit jednu verzi Pythonu v „rychlém“ režimu, zadejte:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

(.venv) C:\...>tox -e py-fast

Podmnožinu testů lze spustit přidáním -- a specifikace testu do příkazového řádku; konkrétní verzi Pythonu lze použít přidáním této verze do cíle testu (např. py310-fast pro spuštění testu fast v Pythonu 3.10).

Pokrytí kódu

BeeWare udržuje ve svém kódovém základu 100% pokrytí větví. Pokud v projektu přidáváte nebo upravujete kód, musíte přidat testovací kód, abyste zajistili pokrytí všech provedených změn.

Nicméně BeeWare je určen pro více platforem i pro více verzí jazyka Python, takže úplné pokrytí nelze ověřit pouze na jedné platformě a jedné verzi Pythonu. Aby se tomuto přizpůsobilo, je v sekci tool.coverage.coverage_conditional_plugin.rules definováno několik podmíněných pravidel pokrytí (např. pyproject.toml lze použít k označení bloku kódu, který nebude proveden při spuštění testovací sady na Windows). Tato pravidla se používají k identifikaci částí kódu, které jsou pokryty pouze na určitých platformách nebo verzích Pythonu.

Je třeba poznamenat, že generování zpráv o pokrytí v různých verzích jazyka Python může být poněkud nevyzpytatelné. Pokud jsou například soubory pokrytí vytvořeny v jedné verzi jazyka Python, ale zpráva o pokrytí je generována v jiné verzi, může zpráva obsahovat falešně pozitivní výsledky u vynechaných větví. Z tohoto důvodu by se při generování zpráv o pokrytí měla vždy používat nejstarší verze jazyka Python, která byla použita k vytvoření souborů pokrytí.

Porozumění výsledkům krytí

Na konci výstupu testu pokrytí by měla být uvedena zpráva o shromážděných údajích o pokrytí:

Jméno    Výkazy   Chybějící pobočka BrPart   Krytí   Chybějící
 ---------------------------------------------------
 CELKEM    7540 0   1040 0  100,0 %

To nám říká, že testovací sada prověřila všechny možné větvení v kódu. Neznamená to sice stoprocentní záruku, že v kódu nejsou žádné chyby, ale znamená to, že prověřujeme každý řádek kódu v kódové základně.

Pokud provedete změny v kódu, může se stát, že v pokrytí vznikne mezera. V takovém případě vám zpráva o pokrytí ukáže, které řádky se neprovádějí. Řekněme například, že jsme provedli změnu v some/interesting_file.py, kde jsme přidali novou logiku. Zpráva o pokrytí by mohla vypadat například takto:

Název Příkazy   Chybějící větev BrPart  Pokrytí   Chybějící
 -------------------------------------------------------------------------------
 src/some/interesting_file.py 111 1     26 0  98,1 %   170, 302–307, 320–335
 -------------------------------------------------------------------------------
 CELKEM 7540 1   1726 0  99,9 %

Z toho vyplývá, že řádek 170, řádky 302–307 a skok z řádku 320 na řádek 335 nejsou v testovací sadě provedeny. Abyste toto pokrytí obnovili, budete muset přidat nové testy (nebo upravit stávající test).

Zpráva o kompatibilitě s hostitelskou platformou a verzí jazyka Python

Můžete vygenerovat zprávu o pokrytí pro vaši platformu a verzi jazyka Python. Chcete-li například spustit sadu testů a vygenerovat zprávu o pokrytí v Pythonu 3.10, zadejte:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

(.venv) C:\...>tox -m test310

Zpráva o pokrytí pro hostitelskou platformu

Pokud má tox k dispozici všechny podporované verze jazyka Python, lze vygenerovat přehled pokrytí pro danou hostitelskou platformu spuštěním následujícího příkazu:

macOSLinuxWindows

(.venv) $ tox p -m test-platform

(.venv) $ tox p -m test-platform

(.venv) C:\...>tox p -m test-platform

Zprávy o pokrytí v HTML

Zprávu o pokrytí HTML lze vygenerovat připojením -html k libovolnému názvu prostředí pokrytí tox, například:

macOSLinuxWindows

(.venv) $ tox -e coverage-platform-html

(.venv) $ tox -e coverage-platform-html

(.venv) C:\...>tox -e coverage-platform-html

Nejde jen o psaní testů!

I když dbáme na to, abychom otestovali veškerý náš kód, nejde jen o to, udržet tuto úroveň testování. Součástí úkolu je také průběžná kontrola kódu. Mohli byste napsat komplexní sadu testů pro konkrétní záchrannou vestu… ale konkrétní záchranná vesta by i tak byla k zamýšlenému účelu k ničemu!

Při vývoji testů byste měli také kontrolovat, zda je základní modul vnitřně konzistentní. Pokud si všimnete názvů metod, které nejsou vnitřně konzistentní (např. něco, co se v jednom modulu jmenuje on_select, ale v jiném on_selected), nebo kde se s daty nezachází konzistentně, označte to a upozorněte nás na to vytvořením ticketu. Nebo, pokud jste si jisti, že víte, co je třeba udělat, vytvořte pull request, který opraví problém, který jste našli.

Pokud řešení problému vyžaduje změny v dokumentaci:

Vytvořit dokumentaci

Před provedením jakýchkoli změn v dokumentaci BeeWare je užitečné ověřit, zda můžete sestavit stávající dokumentaci.

Musíte mít nainstalovaný interpret Python 3.13 a musí být dostupný ve vaší cestě (tj. python3.13 musí spustit interpret Python 3.13).

BeeWare používá tox pro vytváření dokumentace. Následující příkazy tox musí být spuštěny ze stejného umístění jako soubor tox.ini, který se nachází v kořenovém adresáři projektu.

Náhled živé dokumentace

Pro podporu rychlé úpravy dokumentace má BeeWare režim „živého náhledu“.

Živý náhled se vytvoří s varováními!

Live serve je k dispozici pro opakované aktualizace dokumentace. Během aktualizace může dojít k problému s označením. Problémy označené jako WARNING způsobí selhání standardní kompilace, ale live serve je nastaven tak, aby v konzoli zobrazoval varování a pokračoval v kompilaci. To vám umožňuje opakovat aktualizace bez nutnosti restartovat živý náhled.

WARNING se liší od ERROR. Pokud zavedete problém, který je považován za ERROR, živý server selže a bude vyžadovat restart. Nezačne znovu fungovat, dokud nebude problém WARNING vyřešen.

Spuštění živého serveru:

macOSLinuxWindows

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

(venv) C:\...>tox -e docs-live

Tím se vytvoří dokumentace, spustí se webový server pro poskytování dokumentace a bude sledován souborový systém, zda nedošlo k nějakým změnám ve zdrojovém kódu dokumentace.

Po spuštění serveru se v konzoli zobrazí následující výstup:

INFO    -  [11:18:51] Obsluhuje na adrese http://127.0.0.1:8000/

Otevřete prohlížeč a přejděte na uvedenou adresu URL. Nyní můžete začít s iterací dokumentace. Pokud bude zjištěna změna, dokumentace bude znovu sestavena a všechny prohlížeče, které zobrazují upravenou stránku, budou automaticky aktualizovány.

docs-live je první krok

Spuštění docs-live pro práci s živým serverem je určeno pro počáteční iterace. Před odesláním žádosti o stažení byste měli vždy spustit lokální sestavení.

Místní sestavení

Jakmile dokončíte iterace, budete muset provést lokální sestavení dokumentace. Tento proces sestavení je navržen tak, aby selhal v případě jakýchkoli problémů se značkami. To vám umožní zachytit vše, co jste mohli na živém serveru přehlédnout.

Generování lokální sestavení

Pro vytvoření lokální sestavení:

macOSLinuxWindows

(venv) $ tox -e docs

(venv) $ tox -e docs

(venv) C:\...>tox -e docs

Výstup této sestavení bude umístěn v adresáři _build v kořenovém adresáři projektu.

Vytvoření lokálně přeložené sestavy

Dokumentace BeeWare' je přeložena do několika jazyků. Aktualizace anglické dokumentace mohou způsobit problémy v jiných jazykových verzích. Před odesláním žádosti o stažení je důležité ověřit, zda všechny verze fungují správně.

Chcete-li vygenerovat sestavení všech dostupných překladů:

macOSLinuxWindows

(sloveso) $ tox -e docs-all

(sloveso) $ tox -e docs-all

(venv) C:\...>tox -e docs-all

Výstup každé jazykové sestavy bude umístěn v příslušném adresáři _build/html/<languagecode>, kde <languagecode> je dvoumístný nebo pětimístný kód jazyka přidružený ke konkrétnímu jazyku (např. fr pro francouzštinu, it pro italštinu atd.).

Pokud narazíte na problém s jednotlivou sestavou, můžete ji spustit samostatně pomocí příkazu tox -e docs-<languagecode>. Chcete-li například sestavit pouze francouzskou dokumentaci, spusťte:

macOSLinuxWindows

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

(venv) C:\...>tox -e docs-fr

Výstup jednojazyčné sestavy bude umístěn v adresáři _build.

Kontrola dokumentace

Proces sestavení identifikuje problémy s Markdownem, ale BeeWare provádí některé další kontroly stylu a formátování, známé jako „linting“. Chcete-li spustit kontroly lintingu:

macOSLinuxWindows

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

(venv) C:\...>tox -e docs-lint

Tím se ověří, že dokumentace neobsahuje:

• nefunkční odkazy
• špatně napsaná slova

Pokud je platný pravopis slova identifikován jako chybný, přidejte slovo do seznamu v docs/spelling_wordlist. Tím se slovo přidá do slovníku kontroly pravopisu. Při přidávání do tohoto seznamu mějte na paměti:

• Upřednostňujeme americkou pravopisnou normu, s určitými výjimkami pro programátorské slangové výrazy (např. „apps“) a slovesné tvary podstatných jmen (např. „scrollable“).
• Při odkazování na název produktu je třeba používat preferované velká písmena (např. „macOS“, „GTK“, „pytest“, „Pygame“, „PyScript“).
• Pokud je termín používán „jako kód“, měl by být uveden v uvozovkách (like this) namísto přidání do slovníku.

Napsat dokumentaci

Toto jsou kroky, které je třeba dodržet při psaní příspěvku do dokumentace BeeWare.

Aktualizace stávající dokumentace

Pokud upravujete existující dokumenty, budete muset najít soubor v adresáři /docs/en. Struktura souborů odpovídá struktuře stránek, takže soubor můžete najít pomocí URL adresy dokumentace.

Přidání nové dokumentace

Pokud přidáváte nový dokument, je třeba provést několik dalších kroků.

Dokument budete muset vytvořit na příslušném místě v adresáři docs/en. Pro účely této diskuse budeme předpokládat, že přidáváte nový dokument s názvem new_doc.md.

Poté budete muset aktualizovat soubor docs/en/SUMMARY.md, aby zahrnoval váš nový soubor. Soubor SUMMARY.md je uspořádán tak, aby v zásadě odrážel strukturu adresáře docs/en, ale co je důležitější, přímo určuje strukturu levého postranního panelu. Pokud najdete sekci, do které chcete zahrnout new_doc.md, nemusíte v souboru SUMMARY.md nic měnit, pokud vidíte uvedenou cestu se zástupnými znaky. Například:

- ./cesta/k/adresáři/*

Pokud je část, do které chcete vložit new_doc.md, seznamem jednotlivých odkazů Markdown, budete muset přidat explicitní odkaz na ten svůj. Například:

- [Můj nový dokument](new_doc.md)

Psaní dokumentace

Nyní můžete otevřít požadovaný soubor ve svém editoru a začít psát.

Máme průvodce stylem dokumentace, který popisuje naše pokyny pro psaní dokumentace pro BeeWare.

Až budete připraveni odeslat svůj příspěvek:

Přidat poznámku o změně

Mnoho nástrojů BeeWare používá towncrier k pomoci při vytváření poznámek k vydání pro každé vydání. Když odešlete žádost o stažení do jednoho z příslušných nástrojů, bude nutné zahrnout poznámku o změně – tato poznámka o změně se stane záznamem v poznámkách k vydání popisujícím provedenou změnu.

Každý pull request musí obsahovat alespoň jeden soubor v adresáři changes/, který obsahuje krátký popis změny implementované pull requestem. Poznámka ke změně by měla být ve formátu Markdown, v souboru s názvem ve formátu <id>.<fragment type>.md. Pokud změna, kterou navrhujete, opraví chybu nebo implementuje funkci, pro kterou již existuje číslo problému, bude ID číslem tohoto tiketu. Pokud změna nemá odpovídající problém, lze jako ID použít číslo PR. Toto číslo PR nebudete znát, dokud neodešlete žádost o stažení, takže první CI test selže při kontrole towncrier; přidejte poznámku o změně a odešlete aktualizaci PR a CI by pak mělo projít.

Existuje pět typů fragmentů:

• feature: PR přidává nové chování nebo schopnost, která dříve nebyla možná (např. přidání podpory pro nový formát balení nebo novou funkci ve stávajícím formátu balení);
• bugfix: PR opravuje chybu ve stávající implementaci;
• doc: PR představuje významné zlepšení dokumentace;
• removal; PR představuje zpětně nekompatibilní změnu v API BeeWare; nebo
• misc; Drobná nebo administrativní změna (např. oprava překlepu, drobné jazykové upřesnění nebo aktualizace verze závislosti), kterou není nutné oznamovat v poznámkách k vydání.

Tento popis v poznámce ke změně by měl být obecný „marketingový“ souhrn změny z pohledu uživatele, nikoli podrobný technický popis nebo podrobnosti implementace. Liší se od zprávy o potvrzení – zpráva o potvrzení popisuje, co bylo provedeno, aby budoucí vývojáři mohli sledovat důvody změny; poznámka ke změně je popis pro uživatele, kteří nemusí mít znalosti o vnitřním fungování.

Například pokud opravíte chybu související s pojmenováním projektu, zpráva o potvrzení může znít:

Použijte přísnější kontrolu regulárních výrazů, aby nebyly povoleny názvy projektů začínající číslicemi.

Odpovídající poznámka o změně by zněla přibližně takto:

Názvy projektů již nemohou začínat číslicí.

Některé PR zavádějí více funkcí a opravují více chyb nebo zavádějí více změn, které nejsou zpětně kompatibilní. V takovém případě může PR obsahovat více souborů se změnami. Pokud potřebujete spojit dva typy fragmentů se stejným ID, můžete přidat číselnou příponu. Například pokud PR 789 přidalo funkci popsanou v ticketu 123, opravilo chybu popsanou v ticketu 234 a také provedlo dvě zpětně nekompatibilní změny, můžete mít 4 soubory se změnami:

• 123.feature.md
• 234.bugfix.md
• 789.removal.1.md
• 789.removal.2.md

Další informace o typech fragmentů towncrier a fragmentů najdete v části Fragmenty zpráv. Stávající příklady fragmentů zpráv najdete také v adresáři changes repozitáře BeeWare. Pokud je tato složka prázdná, je to pravděpodobně proto, že BeeWare nedávno vydalo novou verzi; soubory se změnami jsou smazány a sloučeny, aby se aktualizovaly poznámky k vydání s každým vydáním. V tomto souboru si můžete prohlédnout požadovaný styl komentářů; v nedávno sloučených PR si můžete prohlédnout, jak formátovat poznámky ke změnám.

Odeslat žádost o stažení

Nyní, když jste potvrdili všechny změny, jste připraveni odeslat žádost o stažení. Abyste zajistili hladký průběh procesu kontroly, měli byste provést několik kroků.

Práce s pre-commit

Při potvrzení jakékoli změny se automaticky spustí pre-commit. Pokud jsou v potvrzení nalezeny nějaké problémy, potvrzení selže. Pokud je to možné, pre-commit provede změny potřebné k opravě nalezených problémů. V následujícím příkladu byla kontrolou ruff nalezena chyba ve formátování kódu:

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) C:\...>git add some/interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

V tomto případě ruff problém automaticky vyřešilo; můžete tedy znovu přidat všechny soubory, které byly upraveny v důsledku kontrol před odesláním, a změnu znovu odeslat. Některé kontroly však budou vyžadovat ruční úpravy. Jakmile tyto změny provedete, znovu přidejte všechny upravené soubory a znovu je odešlete.

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

Jakmile vše proběhne, zobrazí se zpráva o dokončení commitu a váš git log zobrazí váš commit jako nejnovější přírůstek. Nyní jste připraveni odeslat data na GitHub.

Odesílejte své změny na GitHub a vytvořte žádost o stažení.

Při prvním odeslání na GitHub vám bude poskytnuta URL adresa, která vás přenese přímo na stránku GitHub, kde můžete vytvořit nový pull request. Klikněte na URL adresu a vytvořte svůj pull request.

Následující příklad ukazuje, co můžete očekávat na push, s vyznačenou URL adresou.

macOSLinuxWindows

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) C:\...>git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

Pokud jste již aktuální větev odeslali na GitHub, URL adresu znovu neobdržíte. Existují však i jiné způsoby, jak získat URL adresu pro vytvoření PR:

• Přejděte do upstreamového repozitáře, klikněte na „Pull Requests“ (Žádosti o stažení) a poté na „New pull request“ (Nová žádost o stažení) a vyberte, odkud chcete odeslat svou žádost o stažení.
• Pokud jste nedávno provedli push, přejděte do upstreamového repozitáře, najděte banner nad seznamem souborů, který označuje, že repozitář „měl nedávné pushy“, a klikněte na tlačítko „Porovnat a stáhnout požadavek“.
• Použijte příkaz GitHub CLI gh pr create a vyplňte požadované údaje.
• Pomocí příkazu GitHub CLI gh pr create --web otevřete webový prohlížeč na stránce pro vytvoření PR.

Kterákoli z těchto možností vám umožní vytvořit nový pull request.

CLI GitHub: gh

GitHub poskytuje GitHub CLI, které vám umožňuje přístup k mnoha funkcím GitHubu z vašeho terminálu pomocí příkazu gh. Dokumentace GitHub CLI popisuje všechny funkce.

Obsah žádosti o stažení

Název žádosti o stažení musí být informativní, jasný a stručný. Snažte se, aby byl pokud možno krátký, ale v případě potřeby jsou přijatelné i delší názvy. Dobrý název PR by měl osobě bez jakéhokoli kontextu poskytnout přiměřeně solidní představu o tom, jaká chyba nebo funkce je ve vašem PR implementována.

Popis PR musí jasně odrážet změny v PR. Osoba bez jakéhokoli kontextu by měla být schopna přečíst váš popis a získat relativně úplné pochopení toho, proč se změna provádí. Vyhněte se vtipům, idiomům, hovorovým výrazům a zbytečnému formátování, jako je používání velkých písmen nebo nadměrné interpunkce; má se jednat o přímé vysvětlení toho, co se děje ve vašem PR, a vyhýbání se těmto věcem činí popis přístupnějším pro ostatní.

Pokud existují nějaké případy reprodukce nebo testovací režimy, které jste použili a které ještě nejsou součástí změn uvedených v PR, měly by být vysvětleny a zahrnuty do PR. Vysvětlení by mělo zahrnovat způsob jejich spuštění a postup pro reprodukci požadovaného výsledku.

Pokud váš pull request vyřeší problém #1234, měli byste do popisu pull requestu zahrnout text Fixes #1234. Tím se problém automaticky uzavře, jakmile bude pull request sloučen. Stejnou syntaxi #1234 můžete použít i pro odkazy na jiné diskuze, problémy nebo pull requesty. Pro odkaz na problém v jiném repozitáři před číslo vložte znak - například python/cpython#1234 odkazuje na problém 1234 v repozitáři CPython.

Kontinuální integrace

Kontinuální integrace (CI) je proces automatizované kontroly vašich požadavků na stažení. Může zahrnovat jednoduché kontroly, jako je zajištění správného formátování kódu, ale také spuštění testovací sady a vytvoření dokumentace.

Existuje řada změn, které mohou vést k selhání CI. Obecně řečeno, PR, které neprojde CI, nebudeme posuzovat. Pokud vytvoříte pull request a CI selže, nezačneme s posuzováním, dokud neprojde. Pokud vaše změny vedou k selhání, je vaší povinností zjistit důvod a problém vyřešit.

Pokud CI selže, odkazy na selhání se zobrazí v dolní části stránky PR pod nadpisem „Některé kontroly nebyly úspěšné“. Zobrazí se seznam neúspěšných kontrol, který se zobrazí v horní části seznamu všech kontrol, pokud existují i úspěšné kontroly. Pokud kliknete na odkaz na selhání, dostanete se do protokolu. Protokol často poskytuje všechny informace, které potřebujete k zjištění příčiny selhání. Přečtěte si protokol a zkuste zjistit, proč k selhání dochází, a poté proveďte nezbytné kroky k jeho vyřešení.

Občas se může stát, že kontrola CI selže z důvodů, které nesouvisejí s vašimi změnami. Může to být způsobeno problémem na stroji, na kterém se kontrola CI provádí, nebo nestabilitou kontroly CI. Pokud zaznamenáte selhání a jste si poměrně jisti, že nesouvisí s vašimi změnami, přidejte k vaší PR komentář s touto informací a my se na to podíváme.

Chcete-li spustit nový běh CI, musíte do své větve odeslat nové změny.

Pokud se ocitnete v situaci, kdy potřebujete pomoc s úspěšným absolvováním CI, zanechte komentář k PR, dejte nám vědět a my uděláme, co bude v našich silách, abychom vám pomohli.

Kontroly pre-commit a towncrier

Pokud kontrola pre-commit nebo towncrier selže, zablokuje to spuštění většiny zbývajících kontrol CI. Než bude možné spustit kompletní sadu kontrol, je nutné vyřešit příslušné problémy.

Máme omezené zdroje CI. Je důležité si uvědomit, že pokaždé, když provedete push do větve, spustí se CI. Pokud hodláte provést několik změn, je lepší je provést lokálně a poté je všechny najednou odeslat. CI se spustí pouze na nejnovější commit v dávce, čímž se minimalizuje zatížení našeho systému CI.

Proces odeslání PR není dokončen, dokud neprojde CI, nebo dokud neposkytnete vysvětlení, proč tomu tak není.