Ako napísať efektívnu a užitočnú správu Git Commit Message

Správy potvrdenia sú krátkym popisom každého potvrdenia v systéme správy verzií, ako je Git. Keď vykonáte zmeny v súboroch projektu, mali by ste poskytnúť správu vysvetľujúcu, čo robia alebo prečo ste ich urobili.

Záväzné správy slúžia ako forma dokumentácie a komunikácie. Zohrávajú kľúčovú úlohu pri udržiavaní prehľadnej a organizovanej histórie verzií projektu. Naučte sa písať dobré správy o odovzdaní a ostatní členovia vášho tímu ocenia vašu prácu ešte viac.

Štruktúra dobrej správy o záväzku

Dobrý príklad správy odovzdania obsahuje štyri časti: Typ, Popis, Telo a Päta.

Ako:

: 
[voliteľné telo]
[voliteľná päta]

Typ

Typ popisuje druh zmeny vykonanej v súčasnom odovzdaní. Môžete použiť akýkoľvek systém, ktorý dáva zmysel vašim okolnostiam. Tu je napríklad niekoľko vzorových kľúčových slov, ktoré môžete použiť na signalizáciu každého typu zmeny, okrem príkladu použitia:

• feat: vaše zmeny prinášajú novú funkciu.
• opraviť: opravíte chybu.
• refaktor: vaša zmena refaktoruje kód bez opravy chyby alebo pridania novej funkcie.
• test: vykonáte akékoľvek zmeny súvisiace s testovaním. Napríklad, keď si písať testy s Jestom alebo akékoľvek iný testovací rámec vyber ty.
• fuška: zmeny nesúvisiace s opravou, funkciou alebo testom. Napríklad aktualizácia závislostí.
• dokumenty: keď aktualizujete dokumentáciu.
• štýl: zmeny, ktoré neovplyvňujú význam kódu, napríklad pridanie medzier, chýbajúce bodkočiarky atď.
• výkon: zmeny súvisiace so zlepšením výkonu.
• stavať: keď vykonáte zmeny, ktoré ovplyvňujú súbory zostavy.
• ci: zmeny súvisiace s nepretržitou integráciou.
• prejsť späť: pri návrate k predchádzajúcemu odovzdaniu.

Popis

„Popis“ správy odovzdania je stručný a popisný súhrn zmien vykonaných v odovzdaní. Slúži ako nadpis, ktorý vystihuje podstatu odovzdania.

Pri písaní popisu majte na pamäti nasledovné:

• Urobte to dostatočne jasné a konkrétne na to, aby ste odovzdanie opísali na prvý pohľad.
• Spravte to stručne a výstižne. V ideálnom prípade by bolo najlepšie obmedziť ho na 50 znakov alebo menej.
• Napíšte ho v prítomnom čase, aj keď popisujete už vykonané zmeny.
• Pri písaní používajte rozkazovací spôsob.
• Začnite to veľkým písmenom.
• Nekonči to bodkou.

Napríklad:

feat: Implementujte prepínanie tmavého režimu pre domovskú stránku

Tento príklad ukazuje, ako môžete napísať popis potvrdenia, že implementuje tmavý režim. Používa sa feat typu, pretože zavádza novú funkciu.

Telo (voliteľné)

Časť tela správy potvrdenia poskytuje ďalšie podrobnosti a kontext o zmenách vykonaných v potvrdení. Telo nebudete vždy potrebovať, ale môže vám pomôcť poskytnúť viac informácií, vysvetliť zdôvodnenie zmeny alebo opísať akékoľvek technické aspekty.

Tu je niekoľko vecí, ktoré si treba všimnúť pri písaní časti tela správy odovzdania:

• Git nikdy nezalamuje text automaticky, preto ho pri písaní tela ručne zalamujte na 72 znakov. To dáva Gitu dostatok priestoru na odsadenie textu, vďaka čomu je čitateľnejší.
• Pomocou tela vysvetlite, čo sa pri zmene stalo, prečo ste zmenu urobili a zdôvodnenie vašej zmeny.
• Medzi riadkom popisu a telom musíte nechať prázdny riadok. To umožňuje Gitu rozlišovať medzi nimi.
• Ak odovzdanie zavádza viacero zmien alebo ovplyvňuje rôzne oblasti kódovej základne, zvážte použitie odrážok alebo odsekov na rozdelenie úprav. To zlepšuje čitateľnosť a pomáha čitateľom pochopiť rôzne aspekty odovzdania.

Napríklad:

feat: Pridajte GitHub ako poskytovateľa OAuth
Integrujte GitHub ako poskytovateľa OAuth, aby ste umožnili bezproblémové používanie 
overenie pomocou účtov GitHub.
- Implementujte tok autentifikácie OAuth pomocou GitHub API
- Nakonfigurujte potrebné koncové body a nastavenia pre autentifikáciu GitHub
- Aktualizujte používateľské rozhranie tak, aby obsahovalo možnosť prihlásenia na GitHub

Vyššie uvedený príklad ukazuje dobrú správu odovzdania Git pre funkciu, ktorá sa pridáva GitHub ako poskytovateľ OAuth k vašej aplikácii. Táto správa o odovzdaní má stručný súhrnný riadok (50 znakov alebo menej), podrobnejší vysvetľujúci text (zabalený do približne 72 znakov) a odrážky pre ďalšie informácie.

Sekcia päty v správe odovzdania je voliteľná časť, ktorá poskytuje dodatočné informácie alebo metadáta súvisiace s odovzdaním. Zvyčajne sa umiestňuje za časť tela, oddelená prázdnym riadkom. Päta môže obsahovať rôzne typy informácií, ako napríklad odkazy na súvisiace problémy, značky alebo špeciálne poznámky.

Pri odkazovaní na problémy, žiadosti o stiahnutie alebo iné súvisiace položky použite vhodnú syntax alebo formát požadovaný systémom sledovania problémov vášho projektu. To zaisťuje, že odkazy sú správne rozpoznané a prepojené.

Napríklad:

feat: Pridajte GitHub ako poskytovateľa OAuth
Integrujte GitHub ako poskytovateľa OAuth, aby ste umožnili bezproblémové používanie 
overenie pomocou účtov GitHub.
- Implementujte tok autentifikácie OAuth pomocou GitHub API
- Nakonfigurujte potrebné koncové body a nastavenia pre autentifikáciu GitHub
- Aktualizujte používateľské rozhranie tak, aby obsahovalo možnosť prihlásenia na GitHub
Vyriešené: #123
Pozri tiež: #456, #789

Päta odkazuje na súvisiaci problém #123 a uvádza ďalšie súvisiace problémy #456 a #789 pre ďalší kontext.

Pridanie správy o potvrdení

Správy o odovzdaní môžete písať pomocou -m príznak, za ktorým nasleduje správa odovzdania v úvodzovkách (voliteľné, ale odporúčané).

The -m príznak je ideálny pre krátke správy odovzdania, zvyčajne vrátane typu a popisu.

Napríklad:

git commit -m "chore: Zmeniť linter na ESlint"

Ak však vaša správa o odovzdaní vyžaduje viac podrobností, ako je telo a päta, bolo by lepšie, keby ste odovzdanie napísali v textovom editore alebo IDE.

Prípadne môžete napísať dlhé správy o odovzdaní do textového súboru a použiť --súbor príznak na určenie správ odovzdania ako obsahu textového súboru.

Napríklad:

git commit --file commit_message.txt

Keď spustíte príkaz uvedený vyššie, git použije obsah súboru ako správu odovzdania.

Môžete tiež Gitu povedať, aby otvoril váš predvolený editor a napísal dlhšiu správu. Ak máte nastavenú premennú prostredia GIT_EDITOR alebo EDITOR, git otvorí tento program, keď spustíte holú git commit príkaz.

Prečo by ste mali písať dobré správy o záväzkoch

Písanie dobrých správ o odovzdaní je kľúčové pre efektívnu spoluprácu a údržbu kódu. Jasné a popisné správy pomáhajú pochopiť, ladiť a kontrolovať kód. Môžu dokonca prispieť k projektovej dokumentácii alebo poznámkam k vydaniu.

Umožňujú zdieľanie znalostí, bezproblémové začlenenie a podporujú správu verzií. Uprednostňovanie správ o potvrdení kvality zlepšuje vývojové procesy a zabezpečuje udržiavateľnosť kódovej základne.