Kako napisati učinkovitu, korisnu Git Commit poruku

Poruke o predaji kratki su opisi svake obveze u sustavu kontrole verzija poput Gita. Kada uređujete promjene u svojim projektnim datotekama, trebali biste dati poruku koja objašnjava što one rade ili zašto ste ih napravili.

Poruke predaje služe kao oblik dokumentacije i komunikacije. Oni igraju ključnu ulogu u održavanju jasne i organizirane povijesti verzija projekta. Naučite kako pisati dobre poruke predaje i ostali članovi vašeg tima će još više cijeniti vaš rad.

Struktura dobre poruke predaje

Dobar primjer poruke predaje uključuje četiri odjeljka: Vrsta, Opis, Tijelo i Podnožje.

ovako:

: 
[opcionalno tijelo]
[opcionalno podnožje]

Tip

Tip opisuje vrstu promjene napravljene u sadašnjem predanju. Možete koristiti bilo koji sustav koji odgovara vašim okolnostima. Na primjer, ovdje su neki primjeri ključnih riječi koje možete koristiti za signaliziranje svake vrste promjene, uz primjer upotrebe:

• podvig: vaše promjene uvode novu značajku.
• popraviti: popravite grešku.
• refaktor: vaša promjena refaktorira kod bez ispravljanja greške ili dodavanja nove značajke.
• test: napravite bilo kakve promjene vezane uz testiranje. Na primjer, kada ti pisati testove s Jestom ili bilo koji drugi okvir za testiranje ti biraš.
• posao: promjene koje nisu povezane s popravkom, značajkom ili testom. Na primjer, ažuriranje ovisnosti.
• dokumenti: kada ažurirate dokumentaciju.
• stil: promjene koje ne utječu na značenje koda, kao što je dodavanje razmaka, nedostatak točke-zareza, itd.
• izvedba: promjene koje se odnose na poboljšanja performansi.
• izgraditi: kada napravite promjene koje utječu na datoteke za izgradnju.
• ci: promjene vezane uz kontinuiranu integraciju.
• vratiti: kada se vraćate na prethodnu predaju.

Opis

"Opis" poruke urezivanja je sažet i opisni sažetak promjena napravljenih u urezivanju. Služi kao naslov koji hvata bit obveze.

Prilikom pisanja opisa imajte na umu sljedeće:

• Neka bude jasno i dovoljno specifično da na prvi pogled opiše commit.
• Neka bude kratko i sažeto. Najbolje bi bilo ograničiti ga na 50 znakova ili manje.
• Napišite ga u sadašnjem vremenu, čak i ako opisujete već napravljene promjene.
• Koristite imperativ dok ga pišete.
• Počnite velikim slovom.
• Nemojte to završiti mjesečnicom.

Na primjer:

podvig: Implementirajte prekidač tamnog načina rada za početnu stranicu

Ovaj primjer pokazuje kako možete napisati opis za commit koji implementira tamni način rada. Koristi se podvig tipa jer uvodi novu značajku.

Tijelo (nije obavezno)

Odjeljak tijela poruke o uvrštavanju daje dodatne pojedinosti i kontekst o promjenama napravljenim u predaji. Nećete uvijek trebati tijelo, ali ono može pomoći u pružanju više informacija, objasniti obrazloženje promjene ili opisati sva tehnička razmatranja.

Evo nekih stvari koje treba imati na umu dok pišete odjeljak tijela poruke o predaji:

• Git nikada ne prelama tekst automatski, stoga ga ručno prelamajte na 72 znaka kada pišete tijelo. Ovo Gitu daje dovoljno prostora za uvlačenje teksta, čineći ga čitljivijim.
• Upotrijebite tijelo da objasnite što se dogodilo u promjeni, zašto ste unijeli promjenu i obrazloženje vaše promjene.
• Trebate ostaviti prazan redak između retka opisa i tijela. To omogućuje Gitu da ih razlikuje.
• Ako commit uvodi višestruke promjene ili utječe na različita područja kodne baze, razmislite o korištenju točaka ili odlomaka za raščlanjivanje izmjena. Ovo poboljšava čitljivost i pomaže čitateljima da razumiju različite aspekte predaje.

Na primjer:

podvig: Dodajte GitHub kao OAuth davatelja
Integrirajte GitHub kao OAuth davatelja kako biste omogućili besprijekorno 
provjera autentičnosti s GitHub računima.
- Implementirajte tok autentifikacije OAuth s GitHub API-jem
- Konfigurirajte potrebne krajnje točke i postavke za GitHub autentifikaciju
- Ažurirajte korisničko sučelje kako biste uključili opciju prijave na GitHub

Gornji primjer pokazuje dobru Git commit poruku za značajku koja dodaje GitHub kao OAuth pružatelj vašoj prijavi. Ova poruka predaje ima koncizan redak sažetka (50 znakova ili manje), detaljniji tekst objašnjenja (zamotan na oko 72 znaka) i nabrajanje za dodatne informacije.

Odjeljak podnožja u poruci o predaji opcijski je dio koji pruža dodatne informacije ili metapodatke koji se odnose na predaju. Obično se postavlja nakon dijela tijela, odvojen praznim redom. Podnožje može uključivati ​​različite vrste informacija, kao što su reference na povezana pitanja, oznake ili posebne bilješke.

Kada spominjete probleme, zahtjeve za povlačenjem ili druge povezane stavke, koristite odgovarajuću sintaksu ili format koji zahtijeva sustav praćenja problema vašeg projekta. Time se osigurava da su reference pravilno prepoznate i povezane.

Na primjer:

podvig: Dodajte GitHub kao OAuth davatelja
Integrirajte GitHub kao OAuth davatelja kako biste omogućili besprijekorno 
provjera autentičnosti s GitHub računima.
- Implementirajte tok autentifikacije OAuth s GitHub API-jem
- Konfigurirajte potrebne krajnje točke i postavke za GitHub autentifikaciju
- Ažurirajte korisničko sučelje kako biste uključili opciju prijave na GitHub
Rješava: #123
Vidi također: #456, #789

Podnožje upućuje na povezani problem #123 i spominje druge povezane probleme #456 i #789 za dodatni kontekst.

Dodavanje Commit poruke

Možete pisati poruke o predaji pomoću -m zastavica nakon koje slijedi poruka o uvrštavanju u navodnike (neobavezno, ali preporučljivo).

The -m zastavica je idealna za kratke poruke predaje, obično uključujući vrstu i opis.

Na primjer:

git commit -m "zadatak: Promijeni linter u ESlint"

Međutim, kada vaša poruka o uvrštavanju zahtjeva više detalja, kao što su tijelo i podnožje, bilo bi vam bolje da napišete obvezu u uređivaču teksta ili IDE-u.

Alternativno, možete napisati dugačke poruke predaje u tekstualnu datoteku i koristiti --datoteka zastavica za navođenje poruka predaje kao sadržaja tekstualne datoteke.

Na primjer:

git commit --file commit_message.txt

Kada pokrenete gornju naredbu, git će koristiti sadržaj datoteke kao poruku o uvrštavanju.

Također možete reći git-u da otvori vaš zadani uređivač za pisanje duže poruke. Ako imate postavljenu varijablu okruženja GIT_EDITOR ili EDITOR, git će otvoriti taj program kada pokrenete goli git počiniti naredba.

Zašto biste trebali pisati dobre poruke predaje

Pisanje dobrih commit poruka ključno je za učinkovitu suradnju i održavanje koda. Jasne i opisne poruke pomažu u razumijevanju, otklanjanju pogrešaka i pregledu koda. Oni čak mogu doprinijeti projektnoj dokumentaciji ili bilješkama o izdanju.

Omogućuju dijeljenje znanja, glatko uključivanje i podržavaju kontrolu verzija. Davanje prioriteta kvalitetnim porukama predaje poboljšava procese razvoja i osigurava mogućnost održavanja baze koda.