Przejdź do treści

Naprawianie problemu

BeeWare śledzi listę znanych problemów. Każdy z tych problemów jest potencjalnym kandydatem do rozwiązania.

Listę tę można filtrować na różne sposoby. Można na przykład filtrować według platformy, aby skupić się na problemach dotyczących platform, na których można przeprowadzić testy, lub według typu problemu, np. błędy w dokumentacji. Dostępny jest również filtr dla dobrych pierwszych problemów — są to problemy, które zostały zidentyfikowane jako problemy o znanej przyczynie i uważamy, że ich naprawa powinna być stosunkowo prosta (chociaż możemy się mylić w naszej analizie).

Jeśli problem istnieje od ponad 6 miesięcy, jest całkiem możliwe, że został już rozwiązany, więc pierwszym krokiem jest sprawdzenie, czy można go odtworzyć. Skorzystaj z informacji zawartych w zgłoszeniu błędu, aby spróbować odtworzyć problem. Jeśli nie możesz go odtworzyć, zgłoś swoje ustalenia w komentarzu do zgłoszenia i wybierz inny problem.

Jeśli możesz odtworzyć problem – spróbuj go naprawić! Zastanów się, jaka kombinacja kodu realizuje tę funkcję, i spróbuj ustalić, co nie działa prawidłowo.

Nawet jeśli nie jesteś w stanie rozwiązać problemu, warto zgłosić wszystko, co odkryjesz podczas tego procesu, w formie komentarza do zgłoszenia. Jeśli uda Ci się znaleźć źródło problemu, ale nie znajdziesz rozwiązania, ta wiedza często wystarczy, aby ktoś, kto ma większą wiedzę na temat platformy, mógł rozwiązać problem. Jeśli zgłoszenie nie zawiera jeszcze dobrego przypadku odtworzenia (małej aplikacji, która nie robi nic poza odtworzeniem problemu), dostarczenie takiego przypadku może być bardzo pomocne.

Wnoszenie poprawki do problemu

Skonfiguruj środowisko programistyczne

Aby wnieść swój wkład do BeeWare, musisz skonfigurować środowisko programistyczne.

Wymagania wstępne

Należy zainstalować następujące wymagania wstępne.

BeeWare wymaga Python 3.10+. Potrzebna będzie również metoda zarządzania środowiskami wirtualnymi (np. venv).

Możesz sprawdzić wersję zainstalowanego języka Python, uruchamiając:

Python 3.8.10 (wersja domyślna, 20 lipca 2020 r., godz. 16:16:00)

Jeśli masz zainstalowanych więcej niż jedną wersję Pythona, może być konieczne zastąpienie python3 konkretnym numerem wersji (np. python3.13)

Zalecamy unikanie najnowszych wersji Pythona (tj. wersji z numerem mikroversji „.0” lub „.1”, np. 3.14.0). Wynika to z faktu, że narzędzia niezbędne do obsługi Pythona w systemie macOS często nie są dostępne dla najnowszych stabilnych wersji Pythona.

BeeWare wymaga Python 3.10+. Potrzebna będzie również metoda zarządzania środowiskami wirtualnymi (np. venv).

Możesz sprawdzić wersję zainstalowanego języka Python, uruchamiając:

Python 3.8.10 (wersja domyślna, 20 lipca 2020 r., godz. 16:16:00)

Jeśli masz zainstalowanych więcej niż jedną wersję Pythona, może być konieczne zastąpienie python3 konkretnym numerem wersji (np. python3.13)

Zalecamy unikanie najnowszych wersji Pythona (tj. wersji o numerze mikroversji „.0” lub „.1”, np. 3.14.0). Wynika to z faktu, że narzędzia niezbędne do obsługi Pythona w systemie Linux często nie są dostępne dla najnowszych stabilnych wersji Pythona.

BeeWare wymaga Python 3.10+. Potrzebna będzie również metoda zarządzania środowiskami wirtualnymi (np. venv).

Możesz sprawdzić wersję zainstalowanego języka Python, uruchamiając:

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

Jeśli masz zainstalowanych więcej niż jedną wersję Pythona, może być konieczne zastąpienie -3 konkretnym numerem wersji (np. -python3.13)

Zalecamy unikanie najnowszych wersji Pythona (tj. wersji z numerem mikroversji „.0” lub „.1”, np. 3.14.0). Wynika to z faktu, że narzędzia niezbędne do obsługi Pythona w systemie Windows często nie są dostępne dla najnowszych stabilnych wersji Pythona.

Skonfiguruj swoje środowisko programistyczne

Zalecanym sposobem skonfigurowania środowiska programistycznego dla BeeWare jest użycie środowiska wirtualnego, a następnie zainstalowanie wersji programistycznej BeeWare i jej zależności.

Sklonuj repozytorium BeeWare

Następnie przejdź do strony BeeWare na GitHubie, a jeśli jeszcze tego nie zrobiłeś, utwórz fork repozytorium na swoim koncie. Następnie kliknij przycisk „<> Kod” na swoim forku. Jeśli masz zainstalowaną aplikację GitHub Desktop na swoim komputerze, możesz wybrać opcję „Otwórz za pomocą GitHub Desktop”; w przeciwnym razie skopiuj podany adres URL HTTPS i użyj go do sklonowania repozytorium na swój komputer za pomocą wiersza poleceń:

Sforkuj repozytorium BeeWare, a następnie:

$ git clone https://github.com/<twoja nazwa użytkownika>/beeware.git

(zastępując swoją nazwę użytkownika GitHub)

Sforkuj repozytorium BeeWare, a następnie:

$ git clone https://github.com/<twoja nazwa użytkownika>/beeware.git

(zastępując swoją nazwę użytkownika GitHub)

Sforkuj repozytorium BeeWare, a następnie:

C:\...>git clone https://github.com/<twoja nazwa użytkownika>/beeware.git

(zastępując swoją nazwę użytkownika GitHub)

Ustaw repozytorium upstream

Po sklonowaniu swojego forka dodaj repozytorium BeeWare jako zdalne upstream . Dzięki temu lokalna kopia będzie miała odniesienie do oryginalnego repozytorium, co ułatwi synchronizację aktualizacji w miarę upływu czasu.

Będziesz również potrzebować tagów z upstream, aby narzędzia takie jak Toga i Briefcase mogły rozpoznać dokładne numery wersji:

$ 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

Jeśli chcesz, aby Twój fork również zawierał te tagi, możesz je przesłać:

$ git push --tags

Może to być przydatne, jeśli później utworzysz nową kopię i chcesz, aby tagi były dostępne z Twojego forka.

Stwórz środowisko wirtualne

Aby skonfigurować środowisko wirtualne i zaktualizować pip, uruchom:

$ 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

Twoje polecenie powinno teraz mieć przed sobą prefiks (.venv).

Zainstaluj BeeWare

Teraz, gdy masz już kod źródłowy, możesz wykonać edytowalną instalację BeeWare w swoim środowisku programistycznym. Uruchom następujące polecenie:

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

Włącz pre-commit

BeeWare wykorzystuje narzędzie o nazwie pre-commit, które służy do identyfikowania prostych problemów i standaryzacji formatowania kodu. Odbywa się to poprzez zainstalowanie haka git, który automatycznie uruchamia serię linterów kodu przed sfinalizowaniem każdego zatwierdzenia git. Aby włączyć pre-commit, uruchom:

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

Teraz jesteś gotowy, aby rozpocząć hakowanie BeeWare!

Praca z oddziału

Zanim zaczniesz pracować nad zmianą, upewnij się, że utworzyłeś gałąź. Domyślnie po sklonowaniu repozytorium fork zostaniesz przeniesiony do gałęzi main. Jest to bezpośrednia kopia gałęzi BeeWare z main.

Chociaż możesz przesłać pull request z gałęzi main, lepiej tego nie robić. Jeśli prześlesz pull request, który jest prawie poprawny, członek zespołu głównego, który go sprawdzi, może wprowadzić niezbędne zmiany, zamiast prosić o drobne poprawki. Jeśli jednak prześlesz pull request z gałęzi main, recenzenci nie będą mogli wprowadzać zmian.

Praca nad główną gałęzią utrudnia również tobie po zakończeniu pierwszego pull requestu. Jeśli chcesz pracować nad drugim pull requestem, będziesz potrzebować „czystej” kopii głównej gałęzi projektu upstream, na której opierasz swój drugi wkład; jeśli swój pierwszy wkład wykonałeś z gałęzi main, nie masz już dostępnej tej czystej wersji.

Zamiast tego należy wprowadzać zmiany w gałęzi funkcji. Gałąź funkcji ma prostą nazwę, która pozwala zidentyfikować wprowadzoną zmianę. Na przykład, jeśli naprawiasz błąd powodujący problemy z kompilacją w systemie Windows 11, możesz utworzyć gałąź funkcji fix-win11-build. Jeśli błąd dotyczy konkretnego zgłoszonego problemu, często w nazwie gałęzi podaje się numer tego problemu (np. fix-1234).

Aby utworzyć gałąź funkcji fix-win11-build, uruchom:

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

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

(.venv) C:\...>git switch -c fix-win11-build
Odtwórz problem

Nie można naprawić problemu, jeśli w ogóle nie występuje. Dlatego odtworzenie problemu jest warunkiem koniecznym do jego naprawienia. W oprogramowaniu problemy są powszechnie nazywane „błędami” (https://en.wikipedia.org/wiki/Software_bug), a zgłoszenia problemów często nazywane są „raportami o błędach”.

Ktoś zgłosił błąd. Musisz sprawdzić, czy czynności opisane przez zgłaszającego prowadzą do wystąpienia zgłoszonego błędu. Czy możesz odtworzyć ten sam wynik, wykonując dokładnie czynności opisane w zgłoszeniu? Jeśli nie, musisz ustalić, dlaczego.

Błędy w kodzie

W idealnej sytuacji będziesz mieć taką samą konfigurację jak osoba, która zgłosiła błąd, wykonasz opisane kroki i będziesz w stanie odtworzyć błąd zgodnie z opisem. Jednak w wielu przypadkach nie będzie to takie proste. Wiele zgłoszeń błędów zawiera jedynie niejasne wyjaśnienia i niejasny zestaw warunków. Problem polega na tym, że wiele błędów różni się w zależności od zestawu warunków, w tym sposobu interakcji, różnych warunków wstępnych, systemu operacyjnego, wersji systemu operacyjnego, architektury procesora lub tego, czy komputer użytkownika jest stary i wolny, czy nowy i szybki. Im więcej informacji mamy na temat sytuacji związanej z błędem, tym lepiej. Spróbuj odtworzyć zestaw warunków podanych przez zgłaszającego. Jeśli nie jesteś w stanie tego zrobić, kolejnym krokiem może być poproszenie osoby, która zgłosiła błąd, o dodatkowe informacje.

Najlepszym sposobem na odtworzenie błędu jest użycie jak najmniejszej próbki, która nadal pokazuje problem. W większości przypadków osoby zgłaszające błędy nie podają minimalnej próbki; jeśli podają jakąkolwiek próbkę, to jest ona skopiowana bezpośrednio z ich „prawdziwej” aplikacji. Twoim celem będzie zredukowanie zgłoszenia do najprostszej możliwej formy, która ujawnia problem. Najlepszym przypadkiem odtworzenia jest najmniejszy możliwy program. Ta redukcja sama w sobie jest pomocna, ponieważ pozwala określić, na czym polega rzeczywisty problem. Każdy może wziąć minimalny przykład, uruchomić go i zaobserwować opisany błąd.

Błędy w dokumentacji

Błędy w dokumentacji mogą przejawiać się na różne sposoby. Istnieją problemy z formatowaniem, które powodują problemy z renderowaniem. Czasami nie jest to nawet błąd; osoba mogła źle odczytać dokumentację lub popełnić prawdziwy błąd. Nie oznacza to jednak, że dokumentacja nie zawiera żadnych problemów. Treść może być niejasna lub nieprecyzyjna, co pozostawia miejsce na nieporozumienia lub błędną interpretację. Możliwe jest, że koncepcja, która powinna zostać omówiona, nie jest omawiana, ponieważ nie została w ogóle udokumentowana.

W przypadku zgłoszenia błędu dotyczącego dokumentacji należy sprawdzić, czy zgłoszony problem nadal występuje. W przypadku problemów z renderowaniem należy skompilować dokumentację, aby sprawdzić, czy można odtworzyć problem. Problemy związane z treścią wymagają przeczytania dokumentacji w celu sprawdzenia, czy nikt nie zgłosił aktualizacji.

Zaktualizuj problem

Ostatnim krokiem w procesie selekcji jest udokumentowanie swoich ustaleń poprzez dodanie komentarza do zgłoszenia.

Jeśli jesteś w stanie odtworzyć problem dokładnie tak, jak został opisany, to wystarczy. Dodaj komentarz, że potwierdziłeś, że widzisz ten sam problem, dokładnie tak, jak opisał to pierwotny zgłaszający.

Jeśli jesteś w stanie podać dodatkowe informacje, dołącz szczegóły dotyczące tego kontekstu. Może to obejmować możliwość odtworzenia problemu w innym systemie operacyjnym lub przy użyciu innej wersji niektórych programów lub cokolwiek innego, co różni się od pierwotnego zgłoszenia.

Jeśli w oryginalnym zgłoszeniu brakowało szczegółów potrzebnych do odtworzenia problemu, dodaj te szczegóły. Może to obejmować podanie informacji o systemie operacyjnym lub wersji, których nie zawierało oryginalne zgłoszenie, bardziej kompletne logi lub ślady stosu lub jaśniejsze instrukcje dotyczące dokładnej sekwencji operacji potrzebnych do odtworzenia problemu. Jeśli opracowałeś prostszy sposób odtworzenia problemu (lub osoba zgłaszająca problem nie podała przypadku odtworzenia), możesz dołączyć szczegóły dotyczące tej metody odtworzenia.

Jeśli nie możesz odtworzyć problemu, również zostaw komentarz, opisując, co próbowałeś zrobić. Wiedza o tym, gdzie problem nie występuje, jest prawie tak samo ważna jak wiedza o tym, gdzie występuje, ponieważ pomaga to zawęzić zakres możliwych przyczyn. Jeśli masz jakieś teorie na temat dlaczego nie możesz odtworzyć problemu — na przykład, jeśli uważasz, że jest to błąd użytkowania lub że problem został rozwiązany przez ostatnią aktualizację systemu operacyjnego — uwzględnij tę spekulację w swoim komentarzu.

Na koniec możesz przekazać zespołowi głównym wszelkie swoje zalecenia. Jeśli uważasz, że pierwotny raport zawiera błąd, zaproponuj zamknięcie zgłoszenia; jeśli masz teorię na temat przyczyny problemu, również możesz ją przedstawić. Twoje uwagi pomogą zespołowi głównemu ustalić, jak przejść do kolejnego etapu.

Jeśli rozwiązanie problemu wymaga zmian w kodzie:

Pisz, uruchamiaj i testuj kod

Naprawienie błędu lub wdrożenie nowej funkcji będzie wymagało napisania nowego kodu.

Mamy przewodnik stylistyczny dotyczący kodu, w którym przedstawiono wytyczne dotyczące pisania kodu dla BeeWare.

Programowanie sterowane testami

Dobrym sposobem na upewnienie się, że kod będzie działał zgodnie z oczekiwaniami, jest najpierw napisanie przypadku testowego, który to sprawdzi. Ten przypadek testowy powinien początkowo zakończyć się niepowodzeniem, ponieważ kod, który ma sprawdzić, jeszcze nie istnieje. Następnie można wprowadzić zmiany w kodzie niezbędne do pomyślnego przejścia testu i mieć pewność, że napisany kod rozwiązuje problem zgodnie z oczekiwaniami.

Uruchom swój kod

Po napisaniu kodu musisz upewnić się, że działa. Będziesz musiał ręcznie uruchomić kod, aby sprawdzić, czy działa zgodnie z oczekiwaniami. Jeśli jeszcze tego nie zrobiłeś, warto napisać przypadek testowy dla wprowadzonych zmian; jak wspomniano powyżej, test ten powinien zakończyć się niepowodzeniem, jeśli kod zostanie zakomentowany lub nie będzie obecny.

Dodaj swój przypadek testowy do zestawu testów, aby można go było uruchomić razem z pozostałymi testami. Następnym krokiem jest uruchomienie zestawu testów.

Uruchamianie testów oraz pokrycie

BeeWare wykorzystuje tox do zarządzania procesem testowania oraz pytest do obsługi własnego zestawu testów.

Domyślne polecenie tox obejmuje wykonanie:

  • haki przed zatwierdzeniem
  • Sprawdzenie informacji o wydaniu

  • sprawdzanie poprawności kodu

  • zestaw testów dla dostępnych wersji języka Python

  • raportowanie pokrycia kodu

W zasadzie właśnie to uruchamia CI po przesłaniu pull requestu.

Aby uruchomić pełny zestaw testów, wpisz:

(.venv) $ tox

(.venv) $ tox

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

Uruchomienie pełnego zestawu testów może chwilę potrwać. Można to znacznie przyspieszyć, uruchamiając tox równolegle, czyli korzystając z opcji tox p (lub tox run-parallel). W przypadku równoległego uruchamiania zestawu testów otrzymasz mniej informacji zwrotnych na temat postępów w trakcie działania, ale na koniec cyklu testowego nadal pojawi się podsumowanie wszelkich wykrytych problemów. Powinieneś zobaczyć komunikat potwierdzający, że testy zostały przeprowadzone. Możesz zobaczyć SKIPPED testów, ale nigdy nie powinieneś otrzymać żadnych wyników testów FAIL lub ERROR. Przed scaleniem każdej poprawki uruchamiamy nasz pełny zestaw testów. Jeśli proces ten wykryje jakiekolwiek problemy, nie scalamy poprawki. Jeśli znajdziesz błąd lub niepowodzenie testu, oznacza to, że albo coś jest nie tak w Twoim środowisku testowym, albo znalazłeś skrajny przypadek, którego wcześniej nie widzieliśmy — w każdym razie daj nam znać!

Oprócz pomyślnego zakończenia testów powinno to wykazać 100% pokrycie testowe.

Przeprowadzanie różnych wariantów testów

Przeprowadź testy dla wielu wersji języka Python

Domyślnie wiele poleceń tox próbuje uruchomić zestaw testów wielokrotnie – po jednym razie dla każdej wersji języka Python obsługiwanej przez BeeWare. Aby było to możliwe, każda z tych wersji musi być zainstalowana na komputerze użytkownika i dostępna dla procesu [wykrywania]tox języka Python realizowanego przez (https://virtualenv.pypa.io/en/latest/explanation.html#python-discovery). Ogólnie rzecz biorąc, jeśli dana wersja języka Python jest dostępna za pośrednictwem PATH, to tox powinno być w stanie ją znaleźć i wykorzystać.

Uruchom tylko zestaw testów

Jeśli szybko wprowadzasz kolejne wersje nowej funkcji, nie musisz uruchamiać pełnego zestawu testów; możesz uruchomić tylko testy jednostkowe. Aby to zrobić, wpisz:

(.venv) $ tox -e py

(.venv) $ tox -e py

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

Uruchom podzbiór testów

Domyślnie polecenie tox uruchamia wszystkie testy z zestawu testów jednostkowych. Podczas tworzenia nowego testu przydatne może być uruchomienie tylko tego jednego testu. W tym celu można przekazać dowolny specyfikator pytest jako argument polecenia tox. Ścieżki do testów są podawane względem katalogu briefcase. Na przykład, aby uruchomić tylko testy zawarte w jednym pliku, należy wpisać:

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

Nawet jeśli uruchomisz tylko część zestawu testów, nadal otrzymasz raport pokrycia – jednak wyniki pokrycia będą obejmowały wyłącznie te linie kodu, które zostały wykonane przez konkretne testy, które uruchomiłeś.

Uruchom zestaw testów dla konkretnej wersji języka Python

Domyślnie tox -e py zostanie uruchomione przy użyciu interpretera, który na danym komputerze zostanie rozpoznany jako python. Jeśli masz zainstalowanych kilka wersji Pythona i chcesz przetestować konkretną wersję spośród zainstalowanych, możesz wskazać konkretną wersję Pythona do użycia. Na przykład, aby uruchomić zestaw testów w Pythonie 3.10, wpisz:

(.venv) $ tox -e py310

(.venv) $ tox -e py310

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

Podzbiór testów [test-subset] można uruchomić, dodając do wiersza poleceń znak -- oraz specyfikację testu.

Uruchom zestaw testów bez sprawdzania pokrycia (szybko)

Domyślnie polecenie tox uruchamia zestaw testów pytest w trybie jednowątkowym. Można przyspieszyć wykonywanie zestawu testów, uruchamiając go równolegle. Tryb ten nie generuje plików pokrycia ze względu na trudności związane z rejestrowaniem pokrycia w uruchomionych procesach. Aby uruchomić pojedynczą wersję Pythona w trybie „szybkim”, należy wpisać:

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

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

Aby uruchomić podzbiór testów, należy dodać -- oraz specyfikację testu do wiersza poleceń; aby użyć określonej wersji Pythona, należy dodać tę wersję do celu testu (np. py310-fast w celu uruchomienia testu fast w Pythonie 3.10).

Pokrycie kodu

BeeWare zapewnia 100% pokrycie gałęzi w swoim kodzie źródłowym. Dodając lub modyfikując kod w projekcie, należy dodać kod testowy, aby zapewnić pokrycie wszystkich wprowadzonych zmian.

Jednak BeeWare jest przeznaczony dla wielu platform, a także dla wielu wersji języka Python, więc nie da się zweryfikować pełnego pokrycia na jednej platformie i w jednej wersji języka Python. Aby temu zaradzić, w sekcji tool.coverage.coverage_conditional_plugin.rules pliku pyproject.toml zdefiniowano kilka reguł warunkowego pokrycia (np. no-cover-if-is-windows może służyć do oznaczenia bloku kodu, który nie zostanie wykonany podczas uruchamiania zestawu testów w systemie Windows). Reguły te służą do identyfikacji fragmentów kodu, które są objęte pokryciem tylko na określonych platformach lub w określonych wersjach Pythona.

Warto zauważyć, że generowanie raportów pokrycia w różnych wersjach Pythona może przebiegać nieco nieprzewidywalnie. Na przykład, jeśli pliki pokrycia zostały utworzone przy użyciu jednej wersji Pythona, a raportowanie pokrycia odbywa się w innej, raport może zawierać fałszywe alarmy dotyczące pominiętych gałęzi. Z tego powodu do generowania raportów pokrycia należy zawsze używać najstarszej wersji Pythona, w której utworzono pliki pokrycia.

Interpretacja wyników badań

Na końcu wyników testu pokrycia powinno znaleźć się zestawienie zebranych danych dotyczących pokrycia:

Nazwa    Wypowiedzi   Nieobecności   Oddziały   Część   Pokrycie   Brakujące
 ---------------------------------------------------
 RAZEM    7540 0   1040 0  100,0%

Oznacza to, że zestaw testów sprawdził wszystkie możliwe ścieżki rozgałęzień w kodzie. Nie daje to stuprocentowej gwarancji, że nie ma żadnych błędów, ale oznacza, że sprawdzamy każdą linię kodu w całym kodzie źródłowym.

Jeśli wprowadzisz zmiany w kodzie, może to spowodować powstanie luki w pokryciu. W takim przypadku raport pokrycia wskaże, które linie nie są wykonywane. Załóżmy na przykład, że wprowadziliśmy zmianę w some/interesting_file.py, dodając nową logikę. Raport pokrycia mógłby wyglądać mniej więcej tak:

Nazwa Stmts   Miss Branch BrPart  Cover   Brakujące
 -------------------------------------------------------------------------------
 src/some/interesting_file.py 111 1     26 0  98,1%   170, 302-307, 320->335
 -------------------------------------------------------------------------------
 RAZEM 7540 1   1726 0  99,9%

Oznacza to, że wiersz 170, wiersze 302–307 oraz skok rozgałęzienia z wiersza 320 do wiersza 335 nie są wykonywane przez zestaw testów. Aby przywrócić ten poziom pokrycia, należy dodać nowe testy (lub zmodyfikować istniejący test).

Raport dotyczący obsługi platformy hosta i wersji języka Python

Możesz wygenerować raport pokrycia dla swojej platformy i wersji języka Python. Na przykład, aby uruchomić zestaw testów i wygenerować raport pokrycia dla języka Python 3.10, wpisz:

(.venv) $ tox -m test310

(.venv) $ tox -m test310

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

Raport dotyczący zasięgu dla platformy hostującej

Jeśli wszystkie obsługiwane wersje języka Python są dostępne dla tox, wówczas pokrycie dla platformy hosta można sprawdzić, uruchamiając:

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

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

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

Raportowanie zasięgu w formacie HTML

Raport pokrycia HTML można wygenerować, dodając -html do dowolnej nazwy środowiska pokrycia tox, na przykład:

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

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

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

Nie chodzi tylko o pisanie testów!

Chociaż dbamy o to, by przetestować cały nasz kod, zadanie to nie polega tylko na utrzymaniu tego poziomu testowania. Częścią tego zadania jest bieżąca kontrola kodu. Można by napisać obszerny zestaw testów dla konkretnej kamizelki ratunkowej… ale taka kamizelka nadal byłaby bezużyteczna w zamierzonym celu!

Podczas tworzenia testów należy również sprawdzać, czy moduł podstawowy jest spójny wewnętrznie. Jeśli zauważysz nazwy metod, które nie są spójne wewnętrznie (np. coś nazywa się on_select w jednym module, a on_selected w innym) lub dane nie są przetwarzane w spójny sposób, zaznacz to i zgłoś nam ten problem, tworząc zgłoszenie. Jeśli natomiast jesteś pewien, co należy zrobić, utwórz pull request, który naprawi znaleziony problem.

Jeśli rozwiązanie problemu wymaga zmian w dokumentacji:

Dokumentacja budowy

Przed wprowadzeniem jakichkolwiek zmian w dokumentacji BeeWare, warto sprawdzić, czy można skompilować istniejącą dokumentację.

Musisz mieć zainstalowany interpreter języka Python 3.13 i dostępny w ścieżce (tj. python3.13 musi uruchamiać interpreter języka Python 3.13).

BeeWare używa tox do tworzenia dokumentacji. Poniższe polecenia tox muszą być uruchamiane z tej samej lokalizacji co plik tox.ini, który znajduje się w katalogu głównym projektu.

Podgląd dokumentacji na żywo

Aby ułatwić szybką edycję dokumentacji, BeeWare posiada tryb „podglądu na żywo”.

Podgląd na żywo zostanie utworzony wraz z ostrzeżeniami!

Usługa Live Serve umożliwia iterację aktualizacji dokumentacji. Podczas aktualizacji może pojawić się problem z oznaczeniami. Problemy oznaczone jako WARNING spowodują niepowodzenie standardowej kompilacji, jednak usługa Live Serve jest skonfigurowana tak, aby wyświetlać ostrzeżenia w konsoli, kontynuując jednocześnie kompilację. Dzięki temu można przeprowadzać iteracje bez konieczności ponownego uruchamiania podglądu na żywo.

WARNING różni się od ERROR. Jeśli wprowadzisz problem uznawany za ERROR, serwis na żywo nie będzie działał i konieczne będzie jego ponowne uruchomienie. Nie zostanie on ponownie uruchomiony, dopóki problem WARNING nie zostanie rozwiązany.

Aby uruchomić serwer na żywo:

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

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

Spowoduje to utworzenie dokumentacji, uruchomienie serwera WWW do obsługi dokumentacji oraz monitorowanie systemu plików pod kątem wszelkich zmian w źródłach dokumentacji.

Po uruchomieniu serwera w konsoli pojawi się następujący komunikat:

INFO    -  [11:18:51] Obsługa na stronie http://127.0.0.1:8000/

Otwórz przeglądarkę i przejdź do podanego adresu URL. Teraz możesz rozpocząć iterację dokumentacji. W przypadku wykrycia zmiany dokumentacja zostanie ponownie zbudowana, a każda przeglądarka wyświetlająca zmodyfikowaną stronę zostanie automatycznie odświeżona.

docs-live to pierwszy krok

Uruchomienie docs-live w celu pracy z serwerem na żywo służy do wstępnej iteracji. Przed przesłaniem pull requestu należy zawsze uruchomić lokalną kompilację.

Lokalna kompilacja

Po zakończeniu iteracji należy wykonać lokalną kompilację dokumentacji. Proces kompilacji jest zaprojektowany tak, aby zakończył się niepowodzeniem w przypadku wystąpienia jakichkolwiek problemów z oznaczeniami. Pozwala to wychwycić wszystko, co mogło zostać przeoczone na serwerze produkcyjnym.

Generowanie lokalnej kompilacji

Aby wygenerować lokalną kompilację:

(venv) $ tox -e docs

(venv) $ tox -e docs

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

Wynik tej kompilacji zostanie zapisany w katalogu _build w katalogu głównym projektu.

Generowanie lokalnej, przetłumaczonej kompilacji

Dokumentacja BeeWare' jest tłumaczona na wiele języków. Aktualizacje dokumentacji angielskiej mogą powodować problemy w wersjach w innych językach. Przed przesłaniem pull requestu należy sprawdzić, czy wszystkie wersje działają poprawnie.

Aby wygenerować kompilację wszystkich dostępnych tłumaczeń:

(czasownik) $ tox -e docs-all

(czasownik) $ tox -e docs-all

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

Wynik każdej kompilacji języka będzie znajdował się w powiązanym katalogu _build/html/<languagecode>, gdzie <languagecode> to dwu- lub pięcioznakowy kod języka powiązany z konkretnym językiem (np. fr dla francuskiego, it dla włoskiego itp.).

Jeśli wykryjesz problem z pojedynczą kompilacją, możesz uruchomić tę kompilację osobno, wykonując polecenie tox -e docs-<languagecode>. Na przykład, aby skompilować tylko dokumentację w języku francuskim, uruchom:

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

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

Wynik kompilacji w jednym języku zostanie zapisany w katalogu _build.

Sprawdzanie poprawności dokumentacji

Proces kompilacji wykrywa problemy związane z formatowaniem Markdown, ale BeeWare wykonuje dodatkowe kontrole stylu i formatowania, znane jako „linting”. Aby uruchomić kontrole lintingowe:

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

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

Spowoduje to sprawdzenie, czy dokumentacja nie zawiera:

  • nieaktywne hiperłącza
  • błędnie napisane słowa

Jeśli poprawna pisownia słowa zostanie uznana za błędną, dodaj to słowo do listy w docs/spelling_wordlist. Spowoduje to dodanie słowa do słownika modułu sprawdzania pisowni. Dodając słowo do tej listy, pamiętaj:

  • Preferujemy pisownię amerykańską, z pewnymi swobodami w przypadku kolokwializmów związanych z programowaniem (np. „apps”) oraz czasownikowania rzeczowników (np. „scrollable”).
  • Wszelkie odniesienia do nazw produktów powinny być zapisywane zgodnie z preferowaną wielkością liter (np. „macOS”, „GTK”, „pytest”, „Pygame”, „PyScript”).
  • Jeśli termin jest używany „jako kod”, należy go cytować jako literał (like this), a nie dodawać do słownika.
Napisz dokumentację

Oto kroki, które należy wykonać, aby napisać swój wkład w dokumentację BeeWare.

Aktualizacja istniejącej dokumentacji

Jeśli edytujesz istniejące dokumenty, musisz znaleźć plik w katalogu /docs/en. Struktura plików jest zgodna ze strukturą stron, więc możesz znaleźć plik, korzystając z adresu URL dokumentacji.

Dodawanie nowej dokumentacji

Jeśli dodajesz nowy dokument, musisz wykonać kilka dodatkowych czynności.

Musisz utworzyć dokument w odpowiedniej lokalizacji w katalogu docs/en. Dla celów dyskusji załóżmy, że dodajesz nowy dokument o nazwie new_doc.md.

Następnie należy zaktualizować plik docs/en/SUMMARY.md, aby uwzględnić nowy plik. Plik SUMMARY.md jest zorganizowany w sposób zasadniczo odzwierciedlający strukturę katalogów docs/en, ale co ważniejsze, bezpośrednio określa strukturę lewego paska bocznego. Jeśli zlokalizujesz sekcję, w której zamierzasz umieścić new_doc.md, nie musisz nic zmieniać w pliku SUMMARY.md, jeśli widzisz wymienioną ścieżkę z symbolem wieloznacznym. Na przykład:

- ./ścieżka/do/katalogu/*

Jeśli sekcja, w której zamierzasz umieścić new_doc.md, jest listą poszczególnych linków Markdown, musisz dodać wyraźny link do swojego. Na przykład:

- [Mój nowy dokument](new_doc.md)

Pisanie dokumentacji

Teraz możesz otworzyć wybrany plik w edytorze i rozpocząć pisanie.

Posiadamy przewodnik stylistyczny dotyczący dokumentacji, który zawiera wytyczne dotyczące pisania dokumentacji dla BeeWare.

Kiedy będziesz gotowy do przesłania swojego wkładu:

Dodaj notatkę dotyczącą zmiany

Wiele narzędzi BeeWare wykorzystuje towncrier do pomocy w tworzeniu informacji o wydaniu dla każdej wersji. Kiedy wysyłasz pull request do jednego z odpowiednich narzędzi, musi on zawierać informację o zmianie — ta informacja stanie się wpisem w informacjach o wydaniu opisującym wprowadzoną zmianę.

Każde żądanie pull musi zawierać co najmniej jeden plik w katalogu changes/, zawierający krótki opis zmiany wprowadzonej przez żądanie pull. Informacja o zmianie powinna być w formacie Markdown, w pliku o nazwie w formacie <id>.<fragment type>.md. Jeśli proponowana zmiana naprawia błąd lub wprowadza funkcję, dla której istnieje numer zgłoszenia, identyfikatorem będzie numer tego zgłoszenia. Jeśli zmiana nie ma odpowiadającego jej zgłoszenia, jako identyfikator można użyć numeru PR. Numer PR będzie znany dopiero po przesłaniu pull requestu, więc pierwsze przejście CI zakończy się niepowodzeniem sprawdzenia towncrier; dodaj notatkę dotyczącą zmiany i prześlij aktualizację PR, a CI powinno przejść pomyślnie.

Istnieje pięć typów fragmentów:

  • feature: PR dodaje nowe zachowanie lub funkcję, które wcześniej nie były możliwe (np. dodanie obsługi nowego formatu pakietów lub nowej funkcji w istniejącym formacie pakietów);
  • bugfix: PR naprawia błąd w istniejącej implementacji;
  • doc: PR stanowi znaczną poprawę dokumentacji;
  • doc: PR stanowi znaczną poprawę dokumentacji;
  • misc; Niewielka lub administracyjna zmiana (np. poprawienie literówki, niewielkie wyjaśnienie językowe lub aktualizacja wersji zależności), która nie wymaga ogłoszenia w informacjach o wydaniu.

Opis w notatce dotyczącej zmian powinien być ogólnym podsumowaniem zmian z punktu widzenia użytkownika, a nie szczegółowym opisem technicznym lub szczegółami wdrożenia. Różni się on od komunikatu zatwierdzenia — komunikat zatwierdzenia opisuje, co zostało zrobione, aby przyszli programiści mogli zrozumieć powody wprowadzenia zmian; notatka dotycząca zmian jest opisem przeznaczonym dla użytkowników, którzy mogą nie mieć wiedzy na temat wewnętrznych aspektów.

Na przykład, jeśli naprawisz błąd związany z nazewnictwem projektu, komunikat zatwierdzenia może brzmieć:

Zastosuj silniejsze sprawdzanie wyrażeń regularnych, aby uniemożliwić stosowanie nazw projektów zaczynających się od cyfr.

Odpowiednia informacja o zmianie brzmiałaby mniej więcej tak:

Nazwy projektów nie mogą już zaczynać się od cyfry.

Niektóre PR wprowadzają wiele funkcji i naprawiają wiele błędów lub wprowadzają wiele zmian niezgodnych wstecznie. W takim przypadku PR może zawierać wiele plików z informacjami o zmianach. Jeśli chcesz powiązać dwa typy fragmentów z tym samym identyfikatorem, możesz dodać numeryczny sufiks. Na przykład, jeśli PR 789 dodał funkcję opisaną w zgłoszeniu 123, zamknął błąd opisany w zgłoszeniu 234, a także wprowadził dwie zmiany niezgodne wstecznie, możesz mieć 4 pliki z informacjami o zmianach:

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

Więcej informacji na temat towncrier i typów fragmentów można znaleźć w sekcji Fragmenty wiadomości. Istniejące przykłady fragmentów wiadomości można również znaleźć w katalogu changes repozytorium BeeWare. Jeśli ten folder jest pusty, prawdopodobnie wynika to z faktu, że BeeWare opublikowało niedawno nową wersję; pliki z informacjami o zmianach są usuwane i łączone w celu aktualizacji informacji o wydaniu wraz z każdym wydaniem. Możesz zapoznać się z tym plikiem, aby zobaczyć wymagany styl komentarzy; możesz również przejrzeć ostatnio scalone PR-y, aby zobaczyć, jak sformatować swoje informacje o zmianach.

Prześlij żądanie ś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.