Jak napsat efektivní a užitečnou zprávu Git Commit Message

Zprávy o potvrzení jsou krátké popisy každého potvrzení v systému správy verzí, jako je Git. Když provedete změny v souborech projektu, měli byste poskytnout zprávu vysvětlující, co dělají nebo proč jste je provedli.

Závazné zprávy slouží jako forma dokumentace a komunikace. Hrají klíčovou roli při udržování přehledné a organizované historie verzí projektu. Naučte se psát dobré zprávy o odevzdání a ostatní členové vašeho týmu vaši práci ocení ještě více.

Struktura zprávy o dobrém závazku

Dobrý příklad zprávy odevzdání obsahuje čtyři části: Typ, Popis, Tělo a Zápatí.

Jako tak:

: 
[volitelné tělo]
[volitelné zápatí]

Typ

Typ popisuje druh změny provedené v aktuálním potvrzení. Můžete použít jakýkoli systém, který dává smysl vašim okolnostem. Zde jsou například ukázková klíčová slova, která můžete použít k signalizaci každého typu změny, spolu s příkladem použití:

• výkon: vaše změny zavádějí novou funkci.
• opravit: opravíte chybu.
• refaktor: vaše změna refaktoruje kód bez opravy chyby nebo přidání nové funkce.
• test: provedete jakékoli změny související s testováním. Například když vy psát testy s Jest nebo nějaký jiný testovací rámec ty vybíráš.
• fuška: změny nesouvisející s opravou, funkcí nebo testem. Například aktualizace závislostí.
• dokumenty: když aktualizujete dokumentaci.
• styl: změny, které neovlivňují význam kódu, jako je přidání mezer, chybějící středníky atd.
• výkon: změny související se zlepšením výkonu.
• stavět: když provedete změny, které ovlivňují soubory sestavení.
• ci: změny související s kontinuální integrací.
• vrátit zpět: při návratu k předchozímu odevzdání.

Popis

„Popis“ zprávy odevzdání je stručné a popisné shrnutí změn provedených v odevzdání. Slouží jako nadpis, který vystihuje podstatu odevzdání.

Při psaní popisu mějte na paměti následující:

• Udělejte to dostatečně jasné a konkrétní, aby to popsalo odevzdání na první pohled.
• Udělejte to stručné a výstižné. V ideálním případě by bylo nejlepší omezit jej na 50 znaků nebo méně.
• Napište jej v přítomném čase, i když popisujete již provedené změny.
• Při psaní používejte rozkazovací způsob.
• Začněte velkým písmenem.
• Nekončete to tečkou.

Například:

feat: Implementujte přepínač tmavého režimu pro domovskou stránku

Tento příklad ukazuje, jak můžete napsat popis pro odevzdání, které implementuje tmavý režim. Používá se výkon typu, protože zavádí novou funkci.

Tělo (volitelné)

Část těla zprávy odevzdání poskytuje další podrobnosti a kontext o změnách provedených v potvrzení. Ne vždy budete potřebovat tělo, ale může vám pomoci poskytnout více informací, vysvětlit zdůvodnění změny nebo popsat jakékoli technické aspekty.

Zde je několik věcí, kterých je třeba si všimnout při psaní části těla zprávy odevzdání:

• Git nikdy nezalamuje text automaticky, takže při psaní těla jej ručně zalamujte na 72 znaků. To dává Gitu dostatek prostoru pro odsazení textu, takže je čitelnější.
• Použijte tělo k vysvětlení toho, co se při změně stalo, proč jste změnu provedli a zdůvodnění vaší změny.
• Mezi popisným řádkem a tělem musíte ponechat prázdný řádek. To Gitu umožňuje rozlišovat mezi nimi.
• Pokud odevzdání zavádí více změn nebo ovlivňuje různé oblasti kódové základny, zvažte použití odrážek nebo odstavců k rozdělení úprav. To zlepšuje čitelnost a pomáhá čtenářům pochopit různé aspekty odevzdání.

Například:

feat: Přidejte GitHub jako poskytovatele OAuth
Integrujte GitHub jako poskytovatele OAuth pro bezproblémové fungování 
ověřování pomocí účtů GitHub.
- Implementujte tok ověřování OAuth pomocí GitHub API
- Nakonfigurujte potřebné koncové body a nastavení pro ověřování GitHub
- Aktualizujte uživatelské rozhraní tak, aby zahrnovalo možnost přihlášení GitHub

Výše uvedený příklad ukazuje dobrou zprávu potvrzení Git pro funkci, která se přidává GitHub jako poskytovatel OAuth k vaší aplikaci. Tato zpráva o odevzdání má stručný souhrn (50 znaků nebo méně), podrobnější vysvětlující text (zalomený do asi 72 znaků) a odrážky pro další informace.

Sekce zápatí ve zprávě odevzdání je volitelná část, která poskytuje další informace nebo metadata související s odevzdáním. Obvykle se umísťuje za část těla a je oddělena prázdným řádkem. Zápatí může obsahovat různé typy informací, jako jsou odkazy na související problémy, značky nebo speciální poznámky.

Při odkazování na problémy, žádosti o stažení nebo jiné související položky použijte příslušnou syntaxi nebo formát vyžadovaný systémem sledování problémů vašeho projektu. To zajišťuje, že jsou odkazy správně rozpoznány a propojeny.

Například:

feat: Přidejte GitHub jako poskytovatele OAuth
Integrujte GitHub jako poskytovatele OAuth pro bezproblémové fungování 
ověřování pomocí účtů GitHub.
- Implementujte tok ověřování OAuth pomocí GitHub API
- Nakonfigurujte potřebné koncové body a nastavení pro ověřování GitHub
- Aktualizujte uživatelské rozhraní tak, aby zahrnovalo možnost přihlášení GitHub
Řešení: #123
Viz také: #456, #789

Zápatí odkazuje na související problém #123 a uvádí další související problémy #456 a #789 pro další kontext.

Přidání zprávy o potvrzení

Můžete psát zprávy o potvrzení pomocí -m příznak následovaný zprávou odevzdání uzavřenou v uvozovkách (volitelné, ale doporučené).

The -m flag je ideální pro krátké zprávy o odevzdání, obvykle včetně typu a popisu.

Například:

git commit -m "chore: Změnit linter na ESlint"

Pokud však vaše zpráva o odevzdání vyžaduje více podrobností, jako je tělo a zápatí, bude lepší napsat odevzdání v textovém editoru nebo IDE.

Případně můžete napsat dlouhé zprávy o potvrzení do textového souboru a použít --soubor příznak k určení zpráv odevzdání jako obsahu textového souboru.

Například:

git commit --file commit_message.txt

Když spustíte výše uvedený příkaz, git použije obsah souboru jako zprávu odevzdání.

Můžete také říct Gitu, aby otevřel váš výchozí editor a napsal delší zprávu. Pokud máte nastavenou proměnnou prostředí GIT_EDITOR nebo EDITOR, git otevře tento program, když spustíte holý git commit příkaz.

Proč byste měli psát dobré zprávy o závazku

Psaní dobrých zpráv o potvrzení je zásadní pro efektivní spolupráci a údržbu kódu. Jasné a popisné zprávy pomáhají pochopit, ladit a kontrolovat kód. Mohou dokonce přispívat do projektové dokumentace nebo poznámek k vydání.

Umožňují sdílení znalostí, hladké začleňování a podporují správu verzí. Upřednostňování zpráv o potvrzení kvality zlepšuje vývojové procesy a zajišťuje udržovatelnost kódové základny.