Dodawanie dokumentacji¶

Możesz mieć najlepsze oprogramowanie na świecie, ale jeśli nikt nie wie, jak z niego korzystać, to jaki ma to sens? Dokumentacja zawsze może zostać ulepszona – i potrzebujemy Twojej pomocy!

Formularze dokumentacji¶

Dokumentacja BeeWare's została napisana przy użyciu MkDocs i Markdown. Staramy się stosować framework Diataxis do strukturyzowania dokumentacji.

Struktura Diataxis opisuje cztery „formy” dokumentacji:

Samouczek — doświadczenie edukacyjne z przewodnikiem, z konkretnym celem projektu.
Poradnik – instrukcje, które prowadzą czytelnika do określonego celu lub rezultatu.
Przewodnik tematyczny – omówienie pojedynczej idei, wyjaśnione w taki sposób, aby podstawowe pojęcia były jasne.
Odniesienie — opisy techniczne konkretnych interfejsów API lub innych interfejsów.

Przed rozpoczęciem pracy nad dokumentacją należy określić, jaki format będzie najbardziej odpowiedni. Wiele propozycji dotyczących dokumentacji jest początkowo opisywanych jako prośba o „samouczek dotyczący X”, ale w większości przypadków faktycznie potrzebne są instrukcje, przewodniki tematyczne lub ulepszone informacje referencyjne.

Jako przykład rozważmy zadanie polegające na napisaniu dokumentacji dotyczącej pieczenia ciasteczek.

Samouczek¶

Samouczek to wprowadzenie, skierowane szczególnie do początkujących, którego celem powinno być przeprowadzenie czytelnika od czystego punktu wyjścia do gotowego produktu. Wymaga on bardzo konkretnych instrukcji i szczegółowych wyjaśnień, które umieszczają kolejne kroki samouczka w odpowiednim kontekście. Nie należy zakładać żadnego doświadczenia czytelnika w zakresie opisywanego narzędzia, chociaż rozsądne jest założenie pewnej podstawowej znajomości języka Python.

Samouczek powinien zawierać regularne punkty kontrolne, w których czytelnik może sprawdzić, czy udało mu się wykonać opisane czynności. W każdym punkcie kontrolnym kryteria sukcesu powinny być jasne. Należy wyraźnie opisać znane przypadki niepowodzeń, w tym wyjaśnienia wszelkich prawdopodobnych błędów lub problemów, które mogą wystąpić u czytelnika. Należy wskazać rzeczy, które ulegają zmianie w wyniku działań podjętych przez czytelnika, nawet jeśli wydają się oczywiste. Zachęca się do powtarzania, zwłaszcza jeśli próbujesz ustalić najlepsze praktyki lub wspólne procesy. Należy unikać wyjaśnień dotyczących wewnętrznych aspektów, podobnie jak alternatywnych ścieżek prowadzących do tego samego wyniku.

Samouczek dotyczący pieczenia ciasteczek to coś więcej niż tylko przepis. Instrukcje zawarte w samouczku powinny być zrozumiałe dla osób, które nigdy wcześniej nie piekły (np. dzieci), i powinny uwzględniać kwestie, które dla doświadczonego piekarza są oczywiste, takie jak sposób ubijania cukru i masła, proces rozgrzewania piekarnika lub czas, przez jaki ciasteczka powinny ostygnąć przed spożyciem. Celem samouczka nie jest wypieczenie ciasteczek, ale przekazanie podstawowych informacji na temat pieczenia. Gotowe ciasteczka są smacznym przysmakiem, który przekonuje kogoś do skorzystania z samouczka.

Poradnik¶

Poradnik powinien skupiać się na konkretnych, rzeczywistych przypadkach użycia i praktycznych wynikach, a nie na teoretycznych wyjaśnieniach. W przeciwieństwie do samouczka, można założyć, że czytelnik ma pewną znajomość istniejących narzędzi. Czytelnik powinien być w stanie postępować zgodnie z poradnikiem od początku do końca i osiągnąć cel, ale może potrzebować do tego pewnej wiedzy. Poradnik powinien zawierać zestaw konkretnych instrukcji lub logicznych kroków, które należy wykonać, aby osiągnąć cel poradnika.

Przepis w książce kucharskiej jest dobrym przykładem instrukcji obsługi. Istnieje wiele przepisów na ciasteczka z kawałkami czekolady i wszystkie one mają wspólne cechy, ale każdy konkretny przepis powinien być możliwy do wykonania od początku do końca i dawać spójny rezultat. Dobry przepis na ciasteczka z kawałkami czekolady nie będzie zawierał dygresji na temat względnych zalet różnych rodzajów cukru lub mąki ani szczegółowych instrukcji dotyczących podstawowych technik lub procesów; będzie zawierał tylko składniki i instrukcje dotyczące pieczenia partii ciasteczek, zakładając, że czytelnik ma podstawową wiedzę na temat pieczenia.

Przewodnik tematyczny¶

Przewodnik tematyczny opisuje pojedynczy temat lub ideę. Może zawierać przykładowy kod lub instrukcje, ale w znacznie większym stopniu skupia się na przedstawieniu ogólnego zarysu danej koncepcji. Może zawierać opinie i alternatywne punkty widzenia, ale należy zachować nacisk na konkretny temat przewodnika.

Przewodnik tematyczny dotyczący pieczenia ciastek może zawierać informacje na temat historii ciastek jako wypieku, wyjaśniać, w jaki sposób procesy przemysłowe wpływają na różnice między ciastkami przemysłowymi a domowymi, lub sugerować sposoby włączenia ciastek do zbilansowanej diety. Sam w sobie nie byłby to zbyt przydatny dokument dla osób chcących upiec ciastka, ale mógłby stanowić źródło informacji umożliwiające osobom zaznajomionym z pieczeniem dostosowanie istniejącego przepisu na ciastka do własnych potrzeb.

Odniesienie¶

Dokumentacja referencyjna ma charakter informacyjny i opisuje specyfikę działania biblioteki narzędzi. Często można ją wygenerować na podstawie samego kodu, ale dobra dokumentacja API może wymagać dodatkowych wyjaśnień i kontekstu. Chociaż czasami może zawierać przykłady użycia, należy unikać szczegółowych wyjaśnień.

Przewodnik po pieczeniu może zawierać opis rodzajów cukru, które można stosować, oraz szczegółowe informacje na temat ich właściwości podczas pieczenia. Opisuje on fakty dotyczące cukru, ale szersza dyskusja na temat wyboru rodzajów cukru powinna być przedmiotem poradnika lub przewodnika tematycznego. Informacje o wartościach odżywczych znajdujące się na większości opakowań produktów spożywczych można uznać za dokumentację referencyjną.

Styl dokumentacji¶

Dokumentacja BeeWare's jest zgodna z wytycznymi zawartymi w przewodniku stylistycznym dokumentacji. Przewodnik ten zawiera podstawowe zasady dotyczące stylu i formatowania oraz proces sprawdzania pisowni. Obejmuje również różne szczegóły składni Markdown, takie jak składnia linków referencyjnych, wskazówki dotyczące pracy z blokami kodu i obsługi obrazów.

Dokumentacja pomocnicza¶

Proponowanie nowej dokumentacji

Masz pomysł na ulepszenie BeeWare – jak zgłosić ten pomysł do rozpatrzenia?

Zrób swoje badania¶

Pierwszym krokiem jest przeszukanie systemu śledzenia problemów BeeWare pod kątem istniejących problemów dotyczących funkcji (problemy oznaczone tagiem „enhancement”), problemów dotyczących dokumentacji (problemy oznaczone tagiem „documentation”) lub wątków dyskusyjnych, aby sprawdzić, czy pomysł został już wcześniej zgłoszony. Jeśli tak, a masz nowe informacje lub pomysły do dodania, dołącz je do istniejącego wątku. Jeśli potrzebujesz pomocy w poszukiwaniach, możesz poprosić o nią na kanale #dev na BeeWare Discord. Być może będziemy w stanie wskazać Ci istniejące wątki, dostarczyć informacji, których możesz nie znać, lub połączyć Twój pomysł z innym, który na pierwszy rzut oka może wydawać się niepowiązany.

Omów pomysł¶

Jeśli nie znajdziesz żadnych istniejących odniesień do swojego pomysłu, rozpocznij wątek dyskusji. Przedstaw ogólny opis celu i zastosowania swojego pomysłu. Dodaj wszelkie przemyślenia na temat tego, jak wyglądałaby ta funkcja, gdyby została wdrożona, np. ogólny kształt interfejsu API, wygląd wizualny funkcji lub dokument, który zostałby dodany. W stosownych przypadkach należy również dołączyć wszelkie badania dotyczące tego, jak pomysł zostałby zrealizowany na różnych platformach.

Po otwarciu wątku dyskusji zespół BeeWare i reszta społeczności udzielą odpowiedzi. Główny zespół postara się przedstawić przynajmniej wstępną opinię na temat Twojego pomysłu w ciągu dwóch dni roboczych. Jeśli pomysł jest szczególnie złożony, bardziej szczegółowa analiza może potrwać do tygodnia. Wydarzenia takie jak święta i konferencje mogą spowodować nieznaczne wydłużenie tych terminów.

To Twoja szansa, aby wziąć udział w dyskusji na temat Twojego pomysłu. Możemy poprosić Cię o podanie dodatkowych szczegółów lub kontekstu. Inni członkowie społeczności również mogą włączyć się do dyskusji, przedstawiając inne perspektywy, sugestie lub kontrpropozycje. Wynik tej dyskusji będzie decydował o kolejnych krokach.

Ważne jest, aby zrozumieć, że nie wszystkie pomysły zostaną zaakceptowane. Proces ten rozpoczyna się od złożenia wniosku, aby uniknąć sytuacji, w której wykonasz całą pracę, a następnie dowiesz się, że istnieje powód, dla którego Twoja zmiana nie zostanie zaakceptowana.

Nie oznacza to, że nie był to dobry pomysł! Mogą istnieć techniczne powody, dla których nie można go wdrożyć. Na przykład możemy odrzucić pomysł, jeśli:

Byłoby to trudne lub niemożliwe do wdrożenia w sposób niezawodny na wszystkich obsługiwanych platformach; lub
Byłoby to trudne do utrzymania lub konserwacja wymagałaby dostępu do technologii lub oprogramowania, które nie są powszechnie dostępne; lub
Obsługuje niszową grupę odbiorców, ale nakłada znaczne obciążenia na innych użytkowników.

Jeśli uznamy, że Twój pomysł nie pasuje, nie oznacza to koniecznie, że powinieneś z niego zrezygnować. Chociaż możemy odrzucić konkretny pomysł, możemy być znacznie bardziej skłonni do dodania interfejsu wtyczki lub innego punktu rozszerzenia, który pozwoliłby Ci zachować tę samą funkcję jako bibliotekę zewnętrzną. W ten sposób możesz mieć tę funkcję, ale bez konkretnych problemów związanych z utrzymaniem lub ograniczeń funkcji, które stałyby się ograniczeniem dla samego projektu.

Przekształć w formalną prośbę o dodanie funkcji¶

Gdy dyskusja doprowadzi do konsensusu w sprawie formy funkcji, można utworzyć nowe zgłoszenie dotyczące funkcji (https://github.com/beeware/beeware/issues/new/choose) w systemie śledzenia zgłoszeń BeeWare, które podsumowuje dyskusję i zawiera link do niej dla kontekstu.

Nie musisz samodzielnie wdrażać swojej propozycji funkcji; możesz zgłosić problem, podając szczegóły swojej propozycji. Jednak samo zgłoszenie problemu nie oznacza, że zostanie on wdrożony. Musisz poczekać, aż ktoś inny zainteresowany tą samą funkcją, czy to inny członek społeczności, czy zespół główny, potencjalnie ją wybierze; nie ma jednak gwarancji, że tak się stanie. Jeśli chcesz mieć gwarancję wdrożenia, musisz wdrożyć ją samodzielnie lub zapłacić komuś, kto zrobi to za Ciebie.

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

Unikaj rozszerzania zakresu projektu

„Rozszerzenie zakresu” ma miejsce, gdy lista problemów rozwiązanych lub funkcji wdrożonych w ramach jednego wkładu znacznie wykracza poza to, co było zamierzone na początku pracy. Zaczynasz od prostego problemu, odkrywasz ściśle powiązany problem i decydujesz się uwzględnić również to rozwiązanie, a potem pojawia się trzeci… Zanim się zorientujesz, masz pull request, który zamyka 5 problemów i dodaje 3 nowe funkcje, w tym dziesiątki plików.

Rozszerzanie zakresu projektu zdarza się każdemu. Jest to pojęcie dobrze znane doświadczonym programistom; wszyscy robiliśmy to wielokrotnie i doświadczyliśmy wszystkich problemów, które się z tym wiążą.

Istnieją bardzo praktyczne powody, dla których należy unikać rozszerzania zakresu projektu. Im większy jest wkład, tym trudniej jest nad nim pracować. Trudniej jest zidentyfikować skrajne przypadki lub potencjalne problemy, co oznacza, że ogólna jakość wkładu może ulec pogorszeniu. Recenzje stają się również trudniejsze, gdy recenzent musi zajmować się wieloma, potencjalnie niepowiązanymi kontekstami. Większy wkład oznacza więcej komentarzy recenzentów, a jako autor wkładu może być trudno śledzić wiele wątków recenzji. Nawet Twoje doświadczenia z GitHubem ucierpią — interfejs użytkownika GitHub spowolni wraz ze wzrostem rozmiaru PR, co oznacza, że nawigacja po plikach za pośrednictwem interfejsu GitHub i próba pozostawienia komentarzy recenzentów stanie się coraz trudniejsza.

Za każdym razem, gdy znajdziesz powód, aby dodać coś do swojego wkładu, co nie jest wyraźnie częścią pierwotnej propozycji lub zgłoszenia błędu, powinieneś rozważyć, czy nie zmierzasz w kierunku rozszerzenia zakresu projektu. Czy istnieją dwie odrębne funkcje, które można by wdrożyć osobno? Czy funkcja może zostać wdrożona ze znanym ograniczeniem lub błędem, a błąd ten naprawiony w kolejnym pull request? Czy jedna część poprawki błędu jest niezależna od drugiej? Jeśli część zmiany można pominąć bez zmiany pierwotnego wkładu, prawdopodobnie należy to zrobić.

Tworzenie oprogramowania to zawsze proces stopniowego doskonalenia. Każdy indywidualny wkład powinien poprawiać stan kodu źródłowego w wyniku scalenia, ale całkowicie dopuszczalne jest pozostawienie błędów lub części funkcji do poprawienia w przyszłości. Może to oznaczać podzielenie pull requestu na wiele części, które można sprawdzić niezależnie, lub zarejestrowanie problemu, aby ktoś inny mógł go zbadać i rozwiązać.

Ograniczenie zakresu każdego wkładu pomaga wszystkim zaangażowanym osobom, w tym również Tobie. Twoi recenzenci, a nawet Ty sam, z pewnością to docenicie.

Dokumentacja budowlana

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:

macOSLinuxWindows

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

Pisanie dokumentacji

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.

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.