Přeskočit obsah

Odeslání žádosti 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:

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

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

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

Vaše žádost o stažení může vyžadovat další obsah, například poznámku o změně, než bude možné ji zkontrolovat.