Kā uzrakstīt efektīvu, noderīgu Git Commit ziņojumu

Apstiprināšanas ziņojumi ir īsi apraksti par katru izpildi tādā versiju kontroles sistēmā kā Git. Veicot izmaiņas projekta failos, jums ir jāsniedz ziņojums, kurā paskaidrots, ko viņi dara vai kāpēc jūs tās veicāt.

Apņemšanās ziņojumi kalpo kā dokumentācijas un saziņas veids. Viņiem ir izšķiroša nozīme skaidras un sakārtotas projekta versiju vēstures uzturēšanā. Uzziniet, kā rakstīt labas saistības, un citi jūsu komandas locekļi novērtēs jūsu darbu vēl vairāk.

Labas apņemšanās ziņojuma struktūra

Labs izpildes ziņojuma piemērs ietver četras sadaļas: tips, apraksts, pamatteksts un kājene.

Tā kā:

: 
[pēc izvēles pamatteksts]
[pēc izvēles kājene]

Tips

Veids apraksta pašreizējās saistībās veikto izmaiņu veidu. Varat izmantot jebkuru sistēmu, kas atbilst jūsu apstākļiem. Piemēram, šeit ir daži atslēgvārdu paraugi, kurus varat izmantot, lai signalizētu par katru izmaiņu veidu, kā arī izmantošanas piemēri.

• varoņdarbs: jūsu veiktās izmaiņas ievieš jaunu funkciju.
• labot: jūs labojat kļūdu.
• faktors: jūsu izmaiņu faktora kods, neizlabojot kļūdu vai nepievienojot jaunu funkciju.
• pārbaude: veicat jebkādas ar testēšanu saistītas izmaiņas. Piemēram, kad jūs raksti testus ar Jestu vai jebkuru cita testēšanas sistēma Izvēlies tu.
• mājas darbi: izmaiņas, kas nav saistītas ar labojumu, līdzekli vai testu. Piemēram, atkarību atjaunināšana.
• dok: kad atjaunināt dokumentāciju.
• stils: izmaiņas, kas neietekmē koda nozīmi, piemēram, atstarpes pievienošana, trūkstošie semikoli utt.
• perf: izmaiņas, kas saistītas ar veiktspējas uzlabojumiem.
• būvēt: kad veicat izmaiņas, kas ietekmē būvfailus.
• ci: izmaiņas, kas saistītas ar nepārtrauktu integrāciju.
• atgriezt: atgriežoties pie iepriekšējās saistības.

Apraksts

Apņemšanās ziņojuma “apraksts” ir īss un aprakstošs kopsavilkums par saistībām veiktajām izmaiņām. Tas kalpo kā virsraksts, kas atspoguļo apņemšanās būtību.

Rakstot aprakstu, ņemiet vērā sekojošo:

• Padariet to pietiekami skaidru un konkrētu, lai īsumā aprakstītu apņemšanos.
• Padariet to īsi un kodolīgi. Ideālā gadījumā vislabāk būtu ierobežot to līdz 50 rakstzīmēm vai mazāk.
• Rakstiet to pašreizējā laikā, pat ja aprakstāt jau veiktās izmaiņas.
• Rakstot izmantojiet imperatīvo noskaņu.
• Sāciet to ar lielo burtu.
• Nebeidziet to ar punktu.

Piemēram:

feat: Ieviesiet tumšā režīma pārslēgšanu sākumlapai

Šis piemērs parāda, kā varat uzrakstīt aprakstu saistībām, kas ievieš tumšo režīmu. Tas izmanto varoņdarbs tipa, jo tas ievieš jaunu līdzekli.

Pamatteksts (pēc izvēles)

Saistības ziņojuma pamatsadaļā ir sniegta papildu informācija un konteksts par saistībām veiktajām izmaiņām. Jums ne vienmēr būs nepieciešams pamatteksts, taču tas var palīdzēt sniegt vairāk informācijas, izskaidrot izmaiņu pamatojumu vai aprakstīt jebkādus tehniskus apsvērumus.

Šeit ir dažas lietas, kas jāņem vērā, rakstot izpildes ziņojuma pamattekstu.

• Git nekad neaplauz tekstu automātiski, tāpēc, rakstot pamattekstu, manuāli aplauziet to līdz 72 rakstzīmēm. Tādējādi Git ir pietiekami daudz vietas teksta atkāpei, padarot to lasāmāku.
• Izmantojiet pamattekstu, lai izskaidrotu, kas notika izmaiņās, kāpēc veicāt izmaiņas, un izmaiņu iemeslus.
• Starp apraksta rindiņu un pamattekstu ir jāatstāj tukša rindiņa. Tas ļauj Git tos atšķirt.
• Ja saistības ievieš vairākas izmaiņas vai ietekmē dažādas kodu bāzes jomas, apsveriet iespēju izmantot aizzīmes vai rindkopas, lai izjauktu izmaiņas. Tas uzlabo lasāmību un palīdz lasītājiem izprast dažādus saistību aspektus.

Piemēram:

feat: pievienojiet GitHub kā OAuth nodrošinātāju
Integrējiet GitHub kā OAuth nodrošinātāju, lai nodrošinātu nevainojamu darbību 
autentifikācija ar GitHub kontiem.
- Ieviesiet OAuth autentifikācijas plūsmu, izmantojot GitHub API
- Konfigurējiet nepieciešamos galapunktus un iestatījumus GitHub autentifikācijai
- Atjauniniet lietotāja interfeisu, lai iekļautu GitHub pieteikšanās opciju

Iepriekš minētajā piemērā parādīts labs Git commit ziņojums funkcijai, kas pievieno GitHub kā OAuth nodrošinātājs uz jūsu pieteikumu. Šim ziņojumam ir īsa kopsavilkuma rindiņa (50 rakstzīmes vai mazāk), detalizētāks skaidrojošs teksts (aptuveni 72 rakstzīmes) un aizzīmju punkti papildu informācijai.

Kājenes sadaļa apstiprināšanas ziņojumā ir neobligāta daļa, kas sniedz papildu informāciju vai metadatus saistībā ar apstiprināšanu. Parasti to novieto aiz virsbūves daļas, atdalot ar tukšu līniju. Kājenē var būt ietverta dažāda veida informācija, piemēram, atsauces uz saistītām problēmām, atzīmes vai īpašas piezīmes.

Atsaucoties uz problēmām, izvilkšanas pieprasījumiem vai citiem saistītiem vienumiem, izmantojiet atbilstošo sintaksi vai formātu, ko pieprasa jūsu projekta problēmu izsekošanas sistēma. Tas nodrošina, ka atsauces tiek pareizi atpazītas un saistītas.

Piemēram:

feat: pievienojiet GitHub kā OAuth nodrošinātāju
Integrējiet GitHub kā OAuth nodrošinātāju, lai nodrošinātu nevainojamu darbību 
autentifikācija ar GitHub kontiem.
- Ieviesiet OAuth autentifikācijas plūsmu, izmantojot GitHub API
- Konfigurējiet nepieciešamos galapunktus un iestatījumus GitHub autentifikācijai
- Atjauniniet lietotāja interfeisu, lai iekļautu GitHub pieteikšanās opciju
Atrisina: #123
Skatīt arī: #456, #789

Kājenē ir atsauce uz saistīto problēmu Nr. 123 un minētas citas saistītās problēmas Nr. 456 un Nr. 789, lai iegūtu papildu kontekstu.

Pievienojot apstiprinājuma ziņojumu

Varat rakstīt apņemšanās ziņojumus, izmantojot -m karodziņš, kam seko apstiprinājuma ziņojums pēdiņās (nav obligāti, bet ieteicams).

The -m karodziņš ir ideāli piemērots īsiem ziņojumiem, kas parasti ietver veidu un aprakstu.

Piemēram:

git commit -m "chore: Mainīt linter uz ESlint"

Tomēr, ja apstiprinājuma ziņojumam ir nepieciešama sīkāka informācija, piemēram, pamatteksts un kājene, labāk ir rakstīt apstiprinājumu teksta redaktorā vai IDE.

Varat arī rakstīt garus ziņojumus teksta failā un izmantot -- fails karodziņš, lai norādītu apstiprināšanas ziņojumus kā teksta faila saturu.

Piemēram:

git commit -- fails commit_message.txt

Palaižot iepriekš minēto komandu, git izmantos faila saturu kā apstiprinājuma ziņojumu.

Varat arī likt git atvērt noklusējuma redaktoru, lai rakstītu garāku ziņojumu. Ja jums ir iestatīts vides mainīgais GIT_EDITOR vai EDITOR, git atvērs šo programmu, kad palaižat tukšu git commit komandu.

Kāpēc jums vajadzētu rakstīt labas saistības

Labu saistību ziņojumu rakstīšana ir ļoti svarīga efektīvai sadarbībai un koda uzturēšanai. Skaidri un aprakstoši ziņojumi palīdz saprast, atkļūdot un pārskatīt kodu. Viņi pat var sniegt ieguldījumu projekta dokumentācijā vai izlaiduma piezīmēs.

Tie nodrošina zināšanu apmaiņu, vienmērīgu iestāšanos un atbalsta versiju kontroli. Kvalitatīvas apstiprināšanas ziņojumu prioritātes noteikšana uzlabo izstrādes procesus un nodrošina kodu bāzes apkopi.