Přidání informací o změnách do poznámek k vydání

Mnoho nástrojů BeeWare používá towncrier k pomoci při vytváření poznámek k vydání pro každé vydání. Když odešlete žádost o stažení do jednoho z příslušných nástrojů, bude nutné zahrnout poznámku o změně – tato poznámka o změně se stane záznamem v poznámkách k vydání popisujícím provedenou změnu.

Každý pull request musí obsahovat alespoň jeden soubor v adresáři changes/, který obsahuje krátký popis změny implementované pull requestem. Poznámka ke změně by měla být ve formátu Markdown, v souboru s názvem ve formátu <id>.<fragment type>.md. Pokud změna, kterou navrhujete, opraví chybu nebo implementuje funkci, pro kterou již existuje číslo problému, bude ID číslem tohoto tiketu. Pokud změna nemá odpovídající problém, lze jako ID použít číslo PR. Toto číslo PR nebudete znát, dokud neodešlete žádost o stažení, takže první CI test selže při kontrole towncrier; přidejte poznámku o změně a odešlete aktualizaci PR a CI by pak mělo projít.

Existuje pět typů fragmentů:

• feature: PR přidává nové chování nebo schopnost, která dříve nebyla možná (např. přidání podpory pro nový formát balení nebo novou funkci ve stávajícím formátu balení);
• bugfix: PR opravuje chybu ve stávající implementaci;
• doc: PR představuje významné zlepšení dokumentace;
• removal; PR představuje zpětně nekompatibilní změnu v API BeeWare; nebo
• misc; Drobná nebo administrativní změna (např. oprava překlepu, drobné jazykové upřesnění nebo aktualizace verze závislosti), kterou není nutné oznamovat v poznámkách k vydání.

Tento popis v poznámce ke změně by měl být obecný „marketingový“ souhrn změny z pohledu uživatele, nikoli podrobný technický popis nebo podrobnosti implementace. Liší se od zprávy o potvrzení – zpráva o potvrzení popisuje, co bylo provedeno, aby budoucí vývojáři mohli sledovat důvody změny; poznámka ke změně je popis pro uživatele, kteří nemusí mít znalosti o vnitřním fungování.

Například pokud opravíte chybu související s pojmenováním projektu, zpráva o potvrzení může znít:

Použijte přísnější kontrolu regulárních výrazů, aby nebyly povoleny názvy projektů začínající číslicemi.

Odpovídající poznámka o změně by zněla přibližně takto:

Názvy projektů již nemohou začínat číslicí.

Některé PR zavádějí více funkcí a opravují více chyb nebo zavádějí více změn, které nejsou zpětně kompatibilní. V takovém případě může PR obsahovat více souborů se změnami. Pokud potřebujete spojit dva typy fragmentů se stejným ID, můžete přidat číselnou příponu. Například pokud PR 789 přidalo funkci popsanou v ticketu 123, opravilo chybu popsanou v ticketu 234 a také provedlo dvě zpětně nekompatibilní změny, můžete mít 4 soubory se změnami:

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

Další informace o typech fragmentů towncrier a fragmentů najdete v části Fragmenty zpráv. Stávající příklady fragmentů zpráv najdete také v adresáři changes repozitáře BeeWare. Pokud je tato složka prázdná, je to pravděpodobně proto, že BeeWare nedávno vydalo novou verzi; soubory se změnami jsou smazány a sloučeny, aby se aktualizovaly poznámky k vydání s každým vydáním. V tomto souboru si můžete prohlédnout požadovaný styl komentářů; v nedávno sloučených PR si můžete prohlédnout, jak formátovat poznámky ke změnám.