Kako napisati učinkovito, uporabno Git Commit sporočilo

Sporočila o objavi so kratki opisi vsake objave v sistemu za nadzor različic, kot je Git. Ko potrdite spremembe v svojih projektnih datotekah, morate zagotoviti sporočilo, ki pojasnjuje, kaj počnejo ali zakaj ste jih naredili.

Sporočila potrditve služijo kot oblika dokumentacije in komunikacije. Imajo ključno vlogo pri vzdrževanju jasne in organizirane zgodovine različic projekta. Naučite se pisati dobra sporočila o predaji in drugi člani vaše ekipe bodo vaše delo še bolj cenili.

Struktura dobrega sporočila o potrditvi

Dober primer sporočila o potrditvi vključuje štiri razdelke: Vrsta, Opis, Telo in Noga.

takole:

: 
[izbirno telo]
[izbirna noga]

Vrsta

Tip opisuje vrsto spremembe, narejene v trenutni objavi. Uporabite lahko kateri koli sistem, ki je primeren za vaše okoliščine. Tukaj je na primer nekaj vzorčnih ključnih besed, ki jih lahko uporabite za signaliziranje vsake vrste spremembe, poleg primera uporabe:

• feat: vaše spremembe uvajajo novo funkcijo.
• popraviti: popraviš napako.
• refaktor: vaša sprememba refaktorira kodo, ne da bi odpravili napako ali dodali novo funkcijo.
• test: naredite kakršne koli spremembe, povezane s testiranjem. Na primer, ko si pisanje testov z Jestom ali katerikoli drugo ogrodje testiranja ti izbiraš.
• opravilo: spremembe, ki niso povezane s popravkom, funkcijo ali preizkusom. Na primer posodabljanje odvisnosti.
• dokumenti: ko posodobite dokumentacijo.
• stil: spremembe, ki ne vplivajo na pomen kode, kot je dodajanje praznega prostora, manjkajočih podpičij itd.
• uspešnost: spremembe v zvezi z izboljšavami delovanja.
• graditi: ko naredite spremembe, ki vplivajo na gradbene datoteke.
• ci: spremembe v zvezi s kontinuirano integracijo.
• povrniti: ko se vrnete na prejšnjo objavo.

Opis

"Opis" sporočila objave je jedrnat in opisen povzetek sprememb, izvedenih v objavi. Služi kot naslov, ki zajame bistvo zaveze.

Ko pišete opis, upoštevajte naslednje:

• Naj bo jasno in dovolj natančno, da na prvi pogled opiše objavo.
• Naj bo kratko in jedrnato. Najbolje bi bilo, če bi ga omejili na 50 znakov ali manj.
• Napišite ga v sedanjiku, tudi če opisujete že narejene spremembe.
• Pri pisanju uporabite nujni način.
• Začnite z veliko začetnico.
• Ne končajte ga z menstruacijo.

Na primer:

podvig: Izvedite preklop temnega načina za domačo stran

Ta primer prikazuje, kako lahko napišete opis za objavo, ki izvaja temni način. Uporablja feat vrsto, ker uvaja novo funkcijo.

Telo (neobvezno)

Razdelek telesa objave sporočila nudi dodatne podrobnosti in kontekst o spremembah, izvedenih v objavi. Ne boste vedno potrebovali telesa, lahko pa vam pomaga zagotoviti več informacij, razložiti razloge za spremembo ali opisati morebitne tehnične vidike.

Tukaj je nekaj stvari, ki jih morate upoštevati pri pisanju telesa sporočila objave:

• Git nikoli ne prelomi besedila samodejno, zato ga ročno previjte v 72 znakov, ko pišete telo. To daje Gitu dovolj prostora za zamik besedila, zaradi česar je bolj berljivo.
• Uporabite telo, da pojasnite, kaj se je zgodilo pri spremembi, zakaj ste naredili spremembo in razloge za vašo spremembo.
• Med opisno vrstico in telesom morate pustiti prazno vrstico. To Gitu omogoča razlikovanje med njimi.
• Če potrditev uvede več sprememb ali vpliva na različna področja kodne baze, razmislite o uporabi točk ali odstavkov za razčlenitev sprememb. To izboljša berljivost in pomaga bralcem razumeti različne vidike potrditve.

Na primer:

podvig: dodajte GitHub kot ponudnika OAuth
Integrirajte GitHub kot ponudnika OAuth, da omogočite brezhibno delovanje 
avtentikacija z računi GitHub.
- Izvedite tok preverjanja pristnosti OAuth z API-jem GitHub
- Konfigurirajte potrebne končne točke in nastavitve za preverjanje pristnosti GitHub
- Posodobite uporabniški vmesnik, da vključite možnost prijave v GitHub

Zgornji primer prikazuje dobro sporočilo o potrditvi Git za funkcijo, ki dodaja GitHub kot ponudnik OAuth vaši prijavi. To sporočilo potrditve ima jedrnato vrstico s povzetkom (50 znakov ali manj), podrobnejše razlagalno besedilo (zavito na približno 72 znakov) in točke za dodatne informacije.

Razdelek noge v sporočilu objave je izbirni del, ki nudi dodatne informacije ali metapodatke, povezane z odobritvijo. Običajno je postavljen za delom telesa in je ločen s prazno vrstico. Noga lahko vključuje različne vrste informacij, kot so sklicevanja na sorodna vprašanja, oznake ali posebne opombe.

Pri sklicevanju na težave, zahteve za vlečenje ali druge povezane elemente uporabite ustrezno sintakso ali obliko, ki jo zahteva sistem za sledenje težavam vašega projekta. To zagotavlja, da so reference pravilno prepoznane in povezane.

Na primer:

podvig: dodajte GitHub kot ponudnika OAuth
Integrirajte GitHub kot ponudnika OAuth, da omogočite brezhibno delovanje 
avtentikacija z računi GitHub.
- Izvedite tok preverjanja pristnosti OAuth z API-jem GitHub
- Konfigurirajte potrebne končne točke in nastavitve za preverjanje pristnosti GitHub
- Posodobite uporabniški vmesnik, da vključite možnost prijave v GitHub
Razrešuje: #123
Glej tudi: #456, #789

Noga se sklicuje na sorodno težavo #123 in omenja druge sorodne težave #456 in #789 za dodaten kontekst.

Dodajanje sporočila o potrditvi

Sporočila o objavi lahko pišete z uporabo -m zastavico, ki ji sledi sporočilo o objavi v narekovajih (izbirno, a priporočljivo).

The -m zastavica je idealna za kratka sporočila o objavi, ki običajno vključujejo vrsto in opis.

Na primer:

git commit -m "opravilo: spremeni linter v ESlint"

Če pa vaše sporočilo obveze zahteva več podrobnosti, kot sta telo in noga, bi bilo bolje, da obvezo napišete v urejevalniku besedil ali IDE.

Druga možnost je, da dolga sporočila o objavi napišete v besedilno datoteko in uporabite --mapa zastavico, da določite sporočila objave kot vsebino besedilne datoteke.

Na primer:

git commit --file commit_message.txt

Ko zaženete zgornji ukaz, bo git uporabil vsebino datoteke kot sporočilo o objavi.

Gitu lahko tudi naročite, naj odpre vaš privzeti urejevalnik za pisanje daljšega sporočila. Če imate nastavljeno spremenljivko okolja GIT_EDITOR ali EDITOR, bo git odprl ta program, ko zaženete golo git commit ukaz.

Zakaj bi morali pisati dobra sporočila za potrditev

Pisanje dobrih sporočil o potrditvi je ključnega pomena za učinkovito sodelovanje in vzdrževanje kode. Jasna in opisna sporočila pomagajo pri razumevanju, odpravljanju napak in pregledih kode. Lahko celo prispevajo k projektni dokumentaciji ali opombam ob izdaji.

Omogočajo izmenjavo znanja, gladko vkrcanje in podpirajo nadzor različic. Dajanje prednosti kakovostnim sporočilom o potrditvi izboljša razvojne procese in zagotavlja vzdržljivost kodne baze.