Przejdź do treści

Przesyłanie żądania ściągnięcia

Po zatwierdzeniu wszystkich zmian możesz przesłać pull request. Aby proces weryfikacji przebiegł sprawnie, należy wykonać kilka czynności.

Praca z pre-commit

Kiedy zatwierdzasz jakąkolwiek zmianę, pre-commit uruchamia się automatycznie. Jeśli zostaną wykryte jakiekolwiek problemy związane z zatwierdzeniem, spowoduje to niepowodzenie zatwierdzenia. Tam, gdzie to możliwe, pre-commit wprowadzi zmiany niezbędne do skorygowania wykrytych problemów. W poniższym przykładzie problem z formatowaniem kodu został wykryty przez sprawdzanie ruff:

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

W tym przypadku ruff automatycznie naprawiło problem, więc możesz ponownie dodać wszystkie pliki, które zostały zmodyfikowane w wyniku sprawdzeń przed zatwierdzeniem, i ponownie zatwierdzić zmianę. Jednak niektóre sprawdzenia będą wymagały ręcznych modyfikacji. Po wprowadzeniu tych zmian ponownie dodaj wszystkie zmodyfikowane pliki i ponownie zatwierdź.

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

Gdy wszystko przebiegnie pomyślnie, pojawi się komunikat informujący o sfinalizowaniu zatwierdzenia, a log git pokaże Twoje zatwierdzenie jako najnowszy dodatek. Teraz możesz przesłać zmiany do GitHub.

Prześlij zmiany do serwisu GitHub i utwórz żądanie ściągnięcia.

Przy pierwszym przesłaniu do serwisu GitHub otrzymasz adres URL, który przeniesie Cię bezpośrednio do strony GitHub, gdzie możesz utworzyć nowe żądanie ściągnięcia. Kliknij ten adres i utwórz żądanie ściągnięcia.

Poniżej przedstawiono przykład tego, czego można się spodziewać na push, z zaznaczonym adresem URL.

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

Jeśli wcześniej przesłałeś bieżącą gałąź do serwisu GitHub, nie otrzymasz ponownie adresu URL. Istnieją jednak inne sposoby uzyskania adresu URL służącego do tworzenia PR:

  • Przejdź do repozytorium upstream, kliknij „Pull Requests” (Żądania ściągnięcia), a następnie „New pull request” (Nowe żądanie ściągnięcia) i wybierz, z którego chcesz przesłać swoje żądanie ściągnięcia.
  • Jeśli ostatnio przesłałeś dane, przejdź do repozytorium upstream, znajdź baner nad listą plików, który wskazuje, że repozytorium „miało ostatnio przesłane dane”, i kliknij przycisk „Porównaj i pobierz żądanie”.
  • Użyj polecenia GitHub CLI gh pr create i wypełnij monity.
  • Użyj polecenia GitHub CLI gh pr create --web, aby otworzyć przeglądarkę internetową na stronie tworzenia PR.

Każda z tych opcji umożliwi Ci utworzenie nowego pull requestu.

Interfejs CLI GitHub: gh

GitHub udostępnia GitHub CLI, które umożliwia dostęp do wielu funkcji GitHub z poziomu terminala za pomocą polecenia gh. Dokumentacja GitHub CLI zawiera opis wszystkich funkcji.

Treść żądania pull

Tytuł pull requestu musi być informacyjny, jasny i zwięzły. Staraj się, aby był jak najkrótszy, ale w razie potrzeby dopuszczalne są też dłuższe tytuły. Dobry tytuł PR powinien dać osobie nieznającej kontekstu dość solidne pojęcie o tym, jaki błąd lub funkcja została zaimplementowana w Twoim PR.

Opis PR musi jasno odzwierciedlać zmiany wprowadzone w PR. Osoba nieznająca kontekstu powinna być w stanie przeczytać opis i uzyskać stosunkowo pełne zrozumienie powodów wprowadzenia zmian. Należy unikać żartów, idiomów, kolokwializmów i niepotrzebnego formatowania, takiego jak używanie wielkich liter lub nadmiernej interpunkcji. Opis ma być prostym wyjaśnieniem tego, co dzieje się w PR, a unikanie tych elementów sprawia, że opis jest bardziej przystępny dla innych.

Jeśli istnieją jakieś przypadki reprodukcji lub stosowane przez Ciebie schematy testowania, które nie zostały uwzględnione w zmianach zawartych w PR, należy je wyjaśnić i uwzględnić w PR. Wyjaśnienie powinno zawierać informacje dotyczące sposobu ich uruchamiania oraz czynności niezbędnych do odtworzenia pożądanego wyniku.

Jeśli Twoje żądanie pull request rozwiąże problem nr 1234, powinieneś umieścić tekst Fixes #1234 w opisie żądania pull request. Spowoduje to automatyczne zamknięcie problemu po scaleniu żądania pull request. Możesz odwoływać się do innych dyskusji, problemów lub żądań pull request, używając tej samej składni #1234. Możesz odwołać się do problemu w innym repozytorium, poprzedzając numer znakiem - na przykład python/cpython#1234 odnosi się do problemu 1234 w repozytorium CPython.

Ciągła integracja

Ciągła integracja (ang. CI) to proces automatycznego sprawdzania pull requestów. Może on obejmować proste kontrole, takie jak sprawdzenie poprawności formatowania kodu, ale także uruchamianie zestawu testów i tworzenie dokumentacji.

Istnieje wiele zmian, które mogą spowodować niepowodzenie CI. Ogólnie rzecz biorąc, nie będziemy recenzować PR, który nie przeszedł CI. Jeśli utworzysz pull request, a CI zakończy się niepowodzeniem, nie rozpoczniemy recenzji, dopóki nie przejdzie on pomyślnie. Jeśli Twoje zmiany spowodują niepowodzenie, Twoim obowiązkiem jest zbadanie przyczyny i rozwiązanie problemu.

W przypadku niepowodzenia CI, linki dotyczące niepowodzeń pojawią się na dole strony PR, pod nagłówkiem „Niektóre kontrole nie powiodły się”. Zobaczysz listę nieudanych kontroli, która pojawi się na górze listy wszystkich kontroli, jeśli są też kontrole, które się powiodły. Jeśli klikniesz na link z niepowodzeniem, przeniesie Cię on do logu. Log często zawiera wszystkie informacje potrzebne do ustalenia przyczyny niepowodzenia. Przeczytaj log i spróbuj ustalić, dlaczego wystąpiło niepowodzenie, a następnie zrób to, co konieczne, aby je rozwiązać.

Czasami kontrola CI zakończy się niepowodzeniem z przyczyn niezwiązanych z wprowadzonymi zmianami. Może to wynikać z problemu na komputerze, na którym przeprowadzana jest kontrola CI, lub z niestabilności samej kontroli. Jeśli zauważysz niepowodzenie i masz pewność, że nie jest ono związane z wprowadzonymi zmianami, dodaj odpowiedni komentarz do swojego PR, a my zajmiemy się tą sprawą.

Aby uruchomić nowe wykonanie CI, musisz wprowadzić nowe zmiany do swojej gałęzi.

Jeśli znajdziesz się w sytuacji, w której potrzebujesz pomocy, aby przejść CI, zostaw komentarz na PR, informując nas o tym, a my zrobimy, co w naszej mocy, aby pomóc.

Kontrole pre-commit i towncrier

Jeśli sprawdzanie pre-commit lub towncrier zakończy się niepowodzeniem, zablokuje to wykonanie większości pozostałych sprawdzeń CI. Aby wykonać pełen zestaw sprawdzeń, należy najpierw rozwiązać odpowiednie problemy.

Mamy ograniczone zasoby CI. Należy pamiętać, że za każdym razem, gdy przesyłasz zmiany do gałęzi, uruchamia się CI. Jeśli zamierzasz wprowadzić wiele zmian, lepiej jest wykonać je lokalnie, a następnie przesłać wszystkie naraz. CI będzie działać tylko na najnowszym commitcie w partii, minimalizując obciążenie naszego systemu CI.

Proces przesyłania PR nie jest zakończony, dopóki nie przejdzie on kontroli CI lub nie podasz wyjaśnienia, dlaczego tak się nie stało.

Twoja prośba o wprowadzenie zmian może wymagać dodatkowej treści, takiej jak informacja o zmianach, zanim będzie mogła zostać przejrzana.