Implementace nové funkce¶

Jakmile bude proces návrhu dokončen, měli byste mít kompletní návrh nové funkce. To znamená, že je čas začít psát!

Pokud vaše funkce vyžaduje implementaci specifickou pro danou platformu, měl by proces návrhu ověřit, že daný nápad může být implementován na všech platformách. Jako osoba, která novou funkci implementuje poprvé, však nejste zodpovědní za implementaci nové funkce pro všechny platformy. Musíte poskytnout kompletní implementaci pro alespoň jednu platformu, včetně testů. Pro všechny ostatní platformy budete muset poskytnout „stub“ implementaci – implementaci, která poskytuje holou definici rozhraní, ale vyvolá NotImplementedError nebo vygeneruje logovou zprávu, že dané chování není na dané platformě implementováno.

Důležitou součástí implementace nové funkce je zajištění jejího úplného zdokumentování. To znamená minimálně zajistit, aby existovala dokumentace API, ale může to také vyžadovat přidání návodu nebo tématického průvodce.

Přispívání novými funkcemi¶

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:

$ python3 --version

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:

$ python3 --version

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/<your username>/beeware.git

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

Rozdělte repozitář BeeWare a poté:

$ git clone https://github.com/<your username>/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/<your username>/beeware.git

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

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

Vyhněte se rozšiřování rozsahu

K „rozšíření rozsahu“ dochází, když seznam vyřešených problémů nebo implementovaných funkcí v rámci jednoho příspěvku výrazně přesáhne původní záměr na začátku práce. Začnete s jednoduchým problémem, objevíte úzce související problém a rozhodnete se zahrnout i jeho opravu, pak třetí… a než se nadějete, máte pull request, který uzavírá 5 problémů a přidává 3 nové funkce, včetně desítek souborů.

Rozšíření rozsahu se stává každému. Je to pojem, který je zkušeným vývojářům velmi dobře známý; všichni jsme to už několikrát zažili a setkali se se všemi problémy, které s tím souvisejí.

Existují velmi praktické důvody, proč se vyhnout rozšiřování rozsahu. Čím větší je příspěvek, tím obtížnější je s ním pracovat. Je těžší identifikovat okrajové případy nebo potenciální problémy, což znamená, že celková kvalita příspěvku může být snížena. Recenze se také stávají náročnějšími, když recenzent musí řešit více potenciálně nesouvisejících kontextů. Větší příspěvek znamená více recenzních komentářů a jako přispěvatel může být obtížné sledovat více recenzních vláken. Utrpí tím i vaše zkušenost s GitHubem – uživatelské rozhraní GitHubu se bude zpomalovat s rostoucí velikostí PR, což znamená, že procházení souborů prostřednictvím rozhraní GitHubu a pokusy o zanechání recenzních komentářů budou stále obtížnější.

Kdykoli najdete důvod přidat do svého příspěvku něco, co není výslovně součástí původního návrhu nebo hlášení o chybě, měli byste zvážit, zda se nevydáváte směrem k rozšiřování rozsahu. Existují dvě odlišné funkce, které by mohly být implementovány samostatně? Mohla by být funkce implementována se známým omezením nebo chybou a tato chyba opravena v následném požadavku na stažení? Je jedna část opravy chyby nezávislá na druhé? Pokud lze část změny vynechat, aniž by došlo ke změně původního příspěvku, pravděpodobně by tak mělo být učiněno.

Vývoj softwaru je vždy proces postupného zlepšování. Každý jednotlivý příspěvek by měl po sloučení zanechat kódovou základnu v lepším stavu, ale je zcela přijatelné ponechat chyby nebo části funkcí jako úkol pro budoucí vylepšení. To může znamenat rozdělení žádosti o stažení na více částí, které lze zkontrolovat samostatně, nebo zaznamenání problému, aby jej mohl někdo jiný prošetřit a vyřešit.

Omezení rozsahu každého příspěvku pomáhá všem zúčastněným, včetně vás. Vaši recenzenti, a dokonce i vy sami, to oceníte.

Implementujte novou funkci

Fixing a bug or implementing a feature will require you to write some new code.

We have a code style guide that outlines our guidelines for writing code for BeeWare.

Test-driven development¶

A good way to ensure your code is going to do what you expect it to, is to first write a test case to test for it. This test case should fail initially, as the code it is testing for is not yet present. You can then write the code changes needed to make the test pass, and know that what you've written is solving the problem you are expecting it to.

Run your code¶

Once your code is written, you need to ensure it runs. You'll need to manually run your code to verify it is doing what you expect. If you haven't already, you'll want to write a test case for your changes; as mentioned above, this test should fail if your code is commented out or not present.

You'll add your test case to the test suite, so it can be run alongside the other tests. The next step is to run the test suite.

Running tests and coverage¶

BeeWare uses tox to manage the testing process and pytest for its own test suite.

The default tox command includes running:

pre-commit hooks
towncrier release note check
documentation linting
test suite for available Python versions
code coverage reporting

This is essentially what is run by CI when you submit a pull request.

To run the full test suite, run:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

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

The full test suite can take a while to run. You can speed it up considerably by running tox in parallel, by running tox p (or tox run-parallel). When you run the test suite in parallel, you'll get less feedback on the progress of the test suite as it runs, but you'll still get a summary of any problems found at the end of the test run. You should get some output indicating that tests have been run. You may see SKIPPED tests, but shouldn't ever get any FAIL or ERROR test results. We run our full test suite before merging every patch. If that process discovers any problems, we don't merge the patch. If you do find a test error or failure, either there's something odd in your test environment, or you've found an edge case that we haven't seen before - either way, let us know!

In addition to the tests passing, this should report 100% test coverage.

Running test variations¶

Run tests for multiple versions of Python¶

By default, many of the tox commands will attempt to run the test suite multiple times, once for each Python version supported by BeeWare. To do this, though, each of the Python versions must be installed on your machine and available to tox's Python discovery process. In general, if a version of Python is available via PATH, then tox should be able to find and use it.

Run only the test suite¶

If you're rapidly iterating on a new feature, you don't need to run the full test suite; you can run only the unit tests. To do this, run:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

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

Run a subset of tests¶

By default, tox will run all tests in the unit test suite. When you're developing your new test, it may be helpful to run just that one test. To do this, you can pass in any pytest specifier as an argument to tox. These test paths are relative to the briefcase directory. For example, to run only the tests in a single file, run:

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

You'll still get a coverage report when running a part of the test suite - but the coverage results will only report the lines of code that were executed by the specific tests you ran.

Run the test suite for a specific Python version¶

By default tox -e py will run using whatever interpreter resolves as python on your machine. If you have multiple Python versions installed, and want to test a specific Python version from the versions you have installed, you can specify a specific Python version to use. For example, to run the test suite on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

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

A subset of tests can be run by adding -- and a test specification to the command line.

Run the test suite without coverage (fast)¶

By default, tox will run the pytest suite in single threaded mode. You can speed up the execution of the test suite by running the test suite in parallel. This mode does not produce coverage files due to complexities in capturing coverage within spawned processes. To run a single python version in "fast" mode, run:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

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

A subset of tests can be run by adding -- and a test specification to the command line; a specific Python version can be used by adding the version to the test target (e.g., py310-fast to run fast on Python 3.10).

Code coverage¶

BeeWare maintains 100% branch coverage in its codebase. When you add or modify code in the project, you must add test code to ensure coverage of any changes you make.

However, BeeWare targets multiple platforms, as well as multiple versions of Python, so full coverage cannot be verified on a single platform and Python version. To accommodate this, several conditional coverage rules are defined in the tool.coverage.coverage_conditional_plugin.rules section of pyproject.toml (e.g., no-cover-if-is-windows can be used to flag a block of code that won't be executed when running the test suite on Windows). These rules are used to identify sections of code that are only covered on particular platforms or Python versions.

Of note, coverage reporting across Python versions can be a bit quirky. For instance, if coverage files are produced using one version of Python but coverage reporting is done on another, the report may include false positives for missed branches. Because of this, coverage reporting should always use the oldest version Python used to produce the coverage files.

Understanding coverage results¶

At the end of the coverage test output there should be a report of the coverage data that was gathered:

Name    Stmts   Miss Branch BrPart   Cover   Missing
----------------------------------------------------
CELKEM 7540 0 1040 0 100,0 %

This tells us that the test suite has executed every possible branching path in the code. This isn't a 100% guarantee that there are no bugs, but it does mean that we're exercising every line of code in the codebase.

If you make changes to the codebase, it's possible you'll introduce a gap in this coverage. When this happens, the coverage report will tell you which lines aren't being executed. For example, lets say we made a change to some/interesting_file.py, adding some new logic. The coverage report might look something like:

Jméno Stmts Chybějící pobočka BrPart Obálka Chybí
--------------------------------------------------------------------------------
src/some/interesting_file.py 111 1 26 0 98,1 % 170, 302–307, 320->335
--------------------------------------------------------------------------------
CELKEM 7540 1 1726 0 99,9 %

This tells us that line 170, lines 302-307, and a branch jumping from line 320 to line 335, are not being executed by the test suite. You'll need to add new tests (or modify an existing test) to restore this coverage.

Coverage report for host platform and Python version¶

You can generate a coverage report for your platform and version of Python. For example, to run the test suite and generate a coverage report on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

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

Coverage report for host platform¶

If all supported versions of Python are available to tox, then coverage for the host platform can be reported by running:

macOSLinuxWindows

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

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

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

Coverage reporting in HTML¶

A HTML coverage report can be generated by appending -html to any of the coverage tox environment names, for instance:

macOSLinuxWindows

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

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

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

It's not just about writing tests!¶

Although we ensure that we test all of our code, the task isn't just about maintaining that level of testing. Part of the task is to audit the code as you go. You could write a comprehensive set of tests for a concrete life jacket… but a concrete life jacket would still be useless for the purpose it was intended!

As you develop tests, you should be checking that the core module is internally consistent as well. If you notice any method names that aren't internally consistent (e.g., something called on_select in one module, but called on_selected in another), or where the data isn't being handled consistently, flag it and bring it to our attention by raising a ticket. Or, if you're confident that you know what needs to be done, create a pull request that fixes the problem you've found.

///

/// details-abstract | 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“.

/// warning | Ž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:



/// tab | macOS



```console
(venv) $ tox -e docs-live

LinuxWindows

(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] Serving on 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

(venv) $ tox -e docs-all

(venv) $ 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:

- ./path/to/directory/*

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:

- [My new document](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.

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