Přehled

Všechny změny kódu a dokumentace by měly být odeslány prostřednictvím požadavku na stažení do GitHub pro tento projekt.

Většina projektů má speciálního průvodce příspěvkem s podrobnostmi o konkrétních projektech. pro daný projekt nebo konkrétní typy příspěvků. Tato dokumentace najdete na stránce Read the Docs. Například Briefcase's dokumentace obsahuje příspěvek průvodce jak pro kód a dokumentace.

Všechny příspěvky by měly být v souladu s BeeWare Code of chování.

Poznámky ke změnám

Některé projekty BeeWare, zejména Briefcase a Toga, vyžadují, aby každý byl požadavek na stažení předložen s poznámkou o změně. Tyto poznámky o změnách jsou při vydání nové verze projektu zkompilovány dohromady, čímž vznikne nová verze. poznámky k vydání pro nové vydání.

Společnost BeeWare používá Towncrier k tomu, aby správu poznámek o změnách.

V adresáři změny by měl být vytvořen soubor s poznámkami o změnách a pojmenován v tomto formátu:

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

Například požadavek na stažení, který opravuje problém #42 na GitHubu, by se jmenoval 42.bugfix.rst. Pokud požadavek na stažení není spojen s konkrétním problém, lze místo něj použít číslo požadavku na stažení. Může být nutné vytvořit požadavek na stažení bez poznámky o změně, abyste získali požadavek na stažení. a pak odeslat aktualizaci, která obsahuje poznámku o změně s číslem nově přiděleným číslem požadavku na stažení.

Typ změny pro poznámku o změně by měl být jeden z následujících:

  • feature
  • bugfix
  • doc
  • odstranění
  • misc

Typ misc je vyhrazen pro změny, které nemají vliv na uživatele, a a není třeba je uvádět v poznámkách k vydání. Drobné typografické opravy v dokumentaci, aktualizace konfigurace CI a opravy chyb v systému funkce, které ještě nebyly oficiálně vydány, jsou příklady těchto oprav. funkcí, které by měly být popsány pomocí značek misc.

Poznámka ke změně by měla být jednořádkovým textem, který poskytuje vysokou úroveň. shrnutí změny z pohledu uživatele, nikoliv hluboký popis změny. technický popis nebo podrobnosti implementace. Je odlišná od od zprávy o revizi. Zpráva o revizi popisuje, co bylo provedeno, takže budoucí vývojáři mohli sledovat odůvodnění změny. Poznámka o změně je popis "směrem k uživateli", popsaný z hlediska nové schopnosti. která je k dispozici jako výsledek změny. Může pomoci představa, že poznámku ke změně jako tiskovou zprávu oznamující změnu, spíše než jako dokument o změně. popisem revize.

Pokud například opravíte chybu způsobenou manipulací s datem, revize nebo popis žádosti o stažení může znít:

Přidání validátoru formátu MM-DD-YYYY do validace nástroje DateWidget řetězec.

Zde je popsána změna, která byla provedena v implementaci - detail které budou užitečné pro osobu provádějící revizi kódu. Nicméně odpovídající poznámka ke změně může znít například takto:

Widgety data mohou nyní přijímat data v americkém formátu.

To popisuje funkční změnu tak, jak ji pocítí koncoví uživatelé. uživatelé. Uživatel si tento popis může přečíst, aniž by musel cokoli vědět. o implementaci.

Styl kódu

Projekty BeeWare používají Pre-commit k automatizaci dodržování stylu kódu. Tyto kontroly jsou definovány v .pre-commit-config.yaml pro každý repozitář a jsou automaticky spouštěny v CI, když je zadán požadavek na vytažení (Pull Request). je otevřen.

Automatizace kontrol před odesláním v místním vývojovém prostředí při každé revizi git spusťte pre-commit install.

Zahrnuté kontroly před odesláním:

  • Black zajišťuje jednotné formátování kódu
  • docformatter zajišťuje jednotné formátování řetězců dokumentů a komentářů
  • pyupgrade zajišťuje, že kód je používá nejnovější osvědčené postupy pro Python
  • isort zajišťuje jednotný import příkazy
  • flake8 kontroluje společné kódování a syntaxe
  • Různé kontroly, které ověřují platnost strukturovaných dokumentů, jako jsou soubory TOML a odstraňují zbytečné bílé znaky

Další pokyny:

  • Vyhněte se používání slova "my" v komentářích, např. "Loop over" místo "We loop". přes"

  • Pro proměnné, funkce a metody používejte podtržítka, nikoli camelCase. .

  • Použijte InitialCaps pro názvy tříd (nebo pro tovární funkce, které vracejí třídy)

  • Použití dokumentových řetězců ve stylu Sphinx a 257; anotace typu s 484 je nepovinná, ale doporučená.

    Například:

    def function_name(param1: int, param2: str) -> bool:
    """Příklad funkce s typy a docstringem.

    :param param1: První parametr.
    :param2: Druhý parametr.

    :returns: Návratová hodnota. True pro úspěch, False v opačném případě.
    """

  • V dokumentech k testům uveďte očekávané chování každého testu. demonstruje. Neuvádějte preambule typu "Testuje, že" nebo "Zajišťuje, že". že".

  • Vyhrazení odkazů na tiket pro nejasné problémy, u kterých má tiket další podrobnosti, které nelze snadno popsat v dokumentech nebo komentáře. Číslo tiketu uvádějte na konci věty, např. takto:

    def test_foo():
    """Testovací řetězec vypadá takto (#123456)."""

  • Není-li uvedeno jinak, postupujte podle 8 (s důrazem na oddíl 2).