Kaip parašyti veiksmingą, naudingą „Git Commit“ pranešimą

Įsipareigojimo pranešimai yra trumpi kiekvieno įsipareigojimo aprašymai versijų valdymo sistemoje, pvz., Git. Kai atliekate projekto failų pakeitimus, turėtumėte pateikti pranešimą, paaiškinantį, ką jie daro arba kodėl juos padarėte.

Įsipareigojimo pranešimai yra dokumentacijos ir komunikacijos forma. Jie atlieka labai svarbų vaidmenį palaikant aiškią ir organizuotą projekto versijų istoriją. Išmokite rašyti gerus įsipareigojimo pranešimus ir kiti jūsų komandos nariai dar labiau įvertins jūsų darbą.

Gero įsipareigojimo pranešimo struktūra

Gerą patvirtinimo pranešimo pavyzdį sudaro keturi skyriai: tipas, aprašas, tekstas ir poraštė.

Kaip taip:

: 
[pasirinktinai]
[pasirenkama poraštė]

Tipas

Tipas apibūdina pakeitimo tipą, atliktą atliekant dabartinį įsipareigojimą. Galite naudoti bet kokią sistemą, atitinkančią jūsų aplinkybes. Pavyzdžiui, čia yra keletas pavyzdinių raktinių žodžių, kuriuos galite naudoti norėdami pranešti apie kiekvieną pakeitimo tipą, kartu su naudojimo pavyzdžiu:

• žygdarbis: jūsų pakeitimai pristato naują funkciją.
• pataisyti: ištaisei klaidą.
• refaktorius: jūsų pakeitimo refaktorių kodas nepataisomas klaidos ar nepridėjus naujos funkcijos.
• bandymas: atliekate bet kokius su testavimu susijusius pakeitimus. Pavyzdžiui, kai jūs rašyk testus su Jestu arba bet koks kita testavimo sistema tu renkiesi.
• nuobodi namų ruoša: pakeitimai, nesusiję su pataisymu, funkcija ar bandymu. Pavyzdžiui, atnaujinti priklausomybes.
• dok: kai atnaujinate dokumentaciją.
• stilius: pakeitimai, kurie neturi įtakos kodo reikšmei, pvz., tarpo pridėjimas, trūksta kabliataškių ir pan.
• perf: pakeitimai, susiję su našumo patobulinimais.
• statyti: kai atliekate pakeitimus, turinčius įtakos kūrimo failams.
• ci: pokyčiai, susiję su nuolatine integracija.
• grįžti: kai grįžtama prie ankstesnio įsipareigojimo.

apibūdinimas

Įsipareigojimo pranešimo „aprašas“ yra glausta ir aprašomoji įsipareigojimo pakeitimų santrauka. Ji tarnauja kaip antraštė, atspindinti įsipareigojimo esmę.

Rašydami aprašymą atminkite šiuos dalykus:

• Padarykite tai pakankamai aiškiai ir konkrečiai, kad iš pirmo žvilgsnio apibūdintumėte įsipareigojimą.
• Padarykite tai trumpai ir glaustai. Idealiu atveju geriausia būtų apriboti iki 50 ar mažiau simbolių.
• Parašykite jį esamuoju laiku, net jei aprašote jau atliktus pakeitimus.
• Rašydami naudokite liepiamąją nuotaiką.
• Pradėkite jį didžiąja raide.
• Nebaikite to tašku.

Pavyzdžiui:

žygdarbis: pagrindiniame puslapyje įdiekite tamsaus režimo perjungiklį

Šiame pavyzdyje parodyta, kaip galite parašyti įsipareigojimo aprašymą įgyvendina tamsųjį režimą. Jis naudoja žygdarbis tipo, nes pristatoma nauja funkcija.

Korpusas (nebūtina)

Įsipareigojimo pranešimo teksto dalyje pateikiama papildomos informacijos ir konteksto apie įsipareigojimo pakeitimus. Jums ne visada reikės kūno, bet jis gali padėti suteikti daugiau informacijos, paaiškinti pakeitimo priežastis arba aprašyti bet kokias technines aplinkybes.

Štai keletas dalykų, į kuriuos reikia atkreipti dėmesį rašant įsipareigojimo pranešimo dalį:

• Git niekada nevynioja teksto automatiškai, todėl rašydami turinį rankiniu būdu suvyniokite jį iki 72 simbolių. Tai suteikia Git pakankamai vietos teksto įtraukimui, todėl jis tampa lengviau skaitomas.
• Naudokite tekstą, kad paaiškintumėte, kas atsitiko pakeitus, kodėl padarėte pakeitimą ir priežastis, kodėl tai padarėte.
• Turite palikti tuščią eilutę tarp aprašo eilutės ir turinio. Tai leidžia Git juos atskirti.
• Jei įsipareigojimas įveda kelis pakeitimus arba turi įtakos skirtingoms kodų bazės sritims, apsvarstykite galimybę naudoti ženklelius arba pastraipas, kad suskirstytumėte pakeitimus. Tai pagerina skaitomumą ir padeda skaitytojams suprasti skirtingus įsipareigojimo aspektus.

Pavyzdžiui:

žygdarbis: pridėkite „GitHub“ kaip „OAuth“ teikėją
Integruokite „GitHub“ kaip „OAuth“ teikėją, kad galėtumėte sklandžiai 
autentifikavimas naudojant GitHub paskyras.
- Įdiekite OAuth autentifikavimo srautą su GitHub API
- Sukonfigūruokite būtinus GitHub autentifikavimo galinius taškus ir nustatymus
- Atnaujinkite vartotojo sąsają, kad įtrauktumėte „GitHub“ prisijungimo parinktį

Aukščiau pateiktame pavyzdyje parodytas geras „Git“ įsipareigojimo pranešimas, skirtas funkcijai, kuri prideda „GitHub“ kaip „OAuth“ teikėjas į jūsų paraišką. Šiame patvirtinimo pranešime yra glausta suvestinės eilutė (50 ar mažiau simbolių), išsamesnis aiškinamasis tekstas (apytiksliai 72 simboliai) ir ženkleliai, skirti papildomai informacijai.

Įsipareigojimo pranešimo poraštės skyrius yra neprivaloma dalis, kurioje pateikiama papildomos informacijos arba metaduomenų, susijusių su įsipareigojimu. Paprastai jis dedamas po kūno dalies, atskirtas tuščia linija. Poraštėje gali būti įvairių tipų informacijos, pvz., nuorodų į susijusias problemas, žymas ar specialias pastabas.

Nurodydami problemas, ištraukimo užklausas ar kitus susijusius elementus naudokite atitinkamą sintaksę arba formatą, kurio reikalauja jūsų projekto problemų stebėjimo sistema. Taip užtikrinama, kad nuorodos būtų tinkamai atpažįstamos ir susietos.

Pavyzdžiui:

žygdarbis: pridėkite „GitHub“ kaip „OAuth“ teikėją
Integruokite „GitHub“ kaip „OAuth“ teikėją, kad galėtumėte sklandžiai 
autentifikavimas naudojant GitHub paskyras.
- Įdiekite OAuth autentifikavimo srautą su GitHub API
- Sukonfigūruokite būtinus GitHub autentifikavimo galinius taškus ir nustatymus
- Atnaujinkite vartotojo sąsają, kad įtrauktumėte „GitHub“ prisijungimo parinktį
Sprendžia: #123
Taip pat žiūrėkite: #456, #789

Poraštėje nurodoma susijusi problema Nr. 123 ir minimos kitos susijusios problemos Nr. 456 ir Nr. 789 dėl papildomo konteksto.

Įsipareigojimo pranešimo pridėjimas

Galite rašyti įsipareigojimo pranešimus naudodami -m vėliavėlė, po kurios nurodomas patvirtinimo pranešimas su kabutėmis (neprivaloma, bet rekomenduojama).

The -m vėliavėlė idealiai tinka trumpiems įsipareigojimo pranešimams, paprastai įskaitant tipą ir aprašymą.

Pavyzdžiui:

git commit -m "chore: pakeiskite linter į ESlint"

Tačiau kai jūsų įsipareigojimo pranešimui reikia daugiau informacijos, pvz., teksto ir poraštės, geriau įsipareigoti parašyti teksto rengyklėje arba IDE.

Arba galite rašyti ilgus įsipareigojimo pranešimus tekstiniame faile ir naudoti --failas vėliavėlė, kad nurodytumėte patvirtinimo pranešimus kaip tekstinio failo turinį.

Pavyzdžiui:

git commit --failas commit_message.txt

Kai paleisite aukščiau pateiktą komandą, git naudos failo turinį kaip patvirtinimo pranešimą.

Taip pat galite nurodyti git atidaryti numatytąjį redaktorių ir parašyti ilgesnį pranešimą. Jei turite GIT_EDITOR arba EDITOR aplinkos kintamąjį, git atidarys tą programą, kai paleisite tuščią git commit komandą.

Kodėl turėtumėte rašyti gerus įsipareigojimo pranešimus

Norint veiksmingai bendradarbiauti ir prižiūrėti kodą, labai svarbu rašyti gerus įsipareigojimo pranešimus. Aiškūs ir aprašomieji pranešimai padeda suprasti, derinti ir peržiūrėti kodą. Jie netgi gali prisidėti prie projekto dokumentų ar išleidimo pastabų.

Jie suteikia galimybę dalytis žiniomis, sklandžiai įsijungti ir palaiko versijų valdymą. Teikiant pirmenybę kokybiškiems įsipareigojimo pranešimams, pagerinami kūrimo procesai ir užtikrinamas kodų bazės priežiūra.