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.

macOSLinuxWindows

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:

$ python3 --version

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:

$ python3 --version

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ń:

macOSLinuxWindows

Sforkuj repozytorium BeeWare, a następnie:

$ git clone https://github.com/<your username>/beeware.git

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

Sforkuj repozytorium BeeWare, a następnie:

$ git clone https://github.com/<your username>/beeware.git

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

Sforkuj repozytorium BeeWare, a następnie:

C:\...>git clone https://github.com/<your username>/beeware.git

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

Stwórz środowisko wirtualne¶

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

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

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:

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

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:

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

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:

macOSLinuxWindows

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

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
----------------------------------------------------
RAZEM 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:

Nazwa Stmts Miss Oddział BrPart Okładka Brakująca
--------------------------------------------------------------------------------
src/some/interesting_file.py 111 1 26 0 98,1% 170, 302-307, 320->335
--------------------------------------------------------------------------------
RAZEM 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.

///

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

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

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



/// tab | macOS



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

LinuxWindows

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

macOSLinuxWindows

(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ń:

macOSLinuxWindows

(venv) $ tox -e docs-all

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

macOSLinuxWindows

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

macOSLinuxWindows

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

- ./path/to/directory/*

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:

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

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

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

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

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.

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

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.