Przegląd

Wszystkie zmiany w kodzie i dokumentacji powinny być przesłane poprzez pull request do repozytorium repozytorium GitHub dla projektu.

Większość projektów ma dedykowany przewodnik dotyczący wkładu ze szczegółowymi informacjami dla tego projektu lub konkretnych rodzajów wkładu. Ta dokumentacja można znaleźć na stronie Read the Docs. Na przykład dokumentacja Briefcase documentation zawiera przewodniki dla obu projektów code i dokumentacja.

Wszystkie zgłoszenia powinny być zgodne z [BeeWare Code of Code of Conduct] (/community/behavior/code-of-conduct/).

Uwagi do zmian

Kilka projektów BeeWare, w szczególności Briefcase i Toga, wymaga, aby każde żądanie pull request jest przesyłany z notatką o zmianie. Te notatki zmian są kompilowane razem, gdy nowe wydanie jest cięte dla projektu, tworząc noty wydania dla nowego wydania.

BeeWare używa Towncrier do zarządzania notatkami o zmianach.

Plik notatki o zmianie powinien zostać utworzony w katalogu changes i nazwany przy użyciu tego formatu:

<PR/Issue #>.<Change Type>.rst

Na przykład, żądanie ściągnięcia, które naprawia błąd #42 GitHub będzie miało nazwę 42.bugfix.rst. Jeśli pull request nie jest powiązany z konkretnym wydaniem, można zamiast tego użyć numeru żądania ściągnięcia. Może być konieczne utworzenie pull requesta bez notatki o zmianie, aby uzyskać przydzielony numer pull requesta. numer, a następnie wypchnąć aktualizację, która zawiera notatkę o zmianie z z nowo przydzielonym numerem pull requesta.

Typy zmian dla notatki zmiany powinny być jednym z poniższych:

  • feature
  • bugfix
  • doc
  • usuwanie
  • misc

Typ misc jest zarezerwowany dla zmian, które nie mają wpływu na użytkowników i nie muszą być odnotowane w informacjach o wydaniu. Drobne poprawki typograficzne w dokumentacji, aktualizacje konfiguracji CI i poprawki błędów dla funkcji, które nie zostały jeszcze formalnie wydane, są przykładami funkcje, które można opisać za pomocą znaczników misc.

Notatka o zmianie powinna być pojedynczą linią tekstu, zapewniającą wysoki poziom podsumowanie zmiany z perspektywy użytkownika, a nie dogłębny opis opis techniczny lub szczegóły implementacji. Różni się ona od komunikatu komunikatu zatwierdzenia. Komunikat zatwierdzenia opisuje, co zostało zrobione, aby przyszli programiści mogą śledzić uzasadnienie zmiany. Notatka o zmianie jest opisem "skierowanym do użytkownika", opisanym w kategoriach nowej możliwości która jest dostępna w wyniku zmiany. Pomocne może być myślenie o jako o komunikacie prasowym ogłaszającym zmianę, a nie o opisie niż opis zatwierdzenia.

Na przykład, jeśli naprawisz błąd spowodowany obsługą daty, komunikat commit lub opis pull requesta może brzmieć

Dodano walidator formatu MM-DD-YYYY do łańcucha walidacji DateWidget łańcuch.

Opisuje zmianę, która została wprowadzona do implementacji - szczegóły które będą pomocne dla osoby przeglądającej kod. Jednakże odpowiednia notatka o zmianie może brzmieć mniej więcej tak:

Widżety daty mogą teraz akceptować daty w formacie amerykańskim.

Opisuje to zmianę funkcjonalną, której doświadczą użytkownicy końcowi. użytkowników końcowych. Użytkownik może przeczytać ten opis bez konieczności posiadania wiedzy o implementacji.

Styl kodu

Projekty BeeWare wykorzystują Pre-commit do automatyzacji przestrzegania stylu kodu. Kontrole te są zdefiniowane w pliku .pre-commit-config.yaml dla każdego repozytorium i są automatycznie uruchamiane w CI, gdy zostanie otwarte żądanie ściągnięcia. jest otwarty.

Aby zautomatyzować sprawdzanie pre-commit w lokalnym środowisku programistycznym przy każdym zatwierdzeniu git, uruchom pre-commit install.

Obejmuje wstępne kontrole:

  • Black zapewnia jednolite formatowanie kodu
  • docformatter zapewnia jednolite formatowanie dla łańcuchów dokumentów i komentarzy
  • Pyupgrade](https://github.com/asottile/pyupgrade) zapewnia, że kod jest używa najnowszych najlepszych praktyk dla Pythona
  • isort zapewnia jednolite instrukcje import oświadczenia
  • flake8 sprawdza typowe błędy kodowania i składni
  • Różne kontrole, które sprawdzają poprawność ustrukturyzowanych dokumentów, takich jak pliki TOML i usuwają niepotrzebne białe znaki

Dodatkowe wytyczne:

  • Unikaj używania "my" w komentarzach, np. "Loop over" zamiast "We loop over". nad"

  • W nazwach zmiennych, funkcji i metod należy używać podkreślników, a nie camelCase. nazwy

  • Użyj InitialCaps dla nazw klas (lub dla funkcji fabrycznych, które zwracają classes)

  • Używaj docstringów w stylu Sphinx i 257; adnotacja typu z 484 jest opcjonalne, ale zalecane.

    Na przykład:

    def function_name(param1: int, param2: str) -> bool:
    """Przykładowa funkcja z typami i docstringiem.

    param param1: Pierwszy parametr.
    param2: Drugi parametr.

    :returns: Wartość zwracana. True dla powodzenia, False w przeciwnym razie.
    """

  • W dokumentacji testów należy określić oczekiwane zachowanie, które każdy test demonstruje. Nie dołączaj preambuł, takich jak "Testuje, że" lub "Zapewnia, że". że".

  • Zarezerwuj odniesienia do zgłoszeń dla niejasnych spraw, w których zgłoszenie ma dodatkowe szczegóły, których nie można łatwo opisać w dokumentach lub komentarzach. Dołącz numer zgłoszenia na końcu zdania, na przykład to:

    def test_foo():
    """Testowy docstring wygląda tak (#123456)."""

  • O ile nie określono inaczej, należy postępować zgodnie z 8 (zwracając szczególną uwagę na Sekcja 2).