Kuinka kirjoittaa tehokas, hyödyllinen Git Commit -viesti

Toimitusviestit ovat lyhyitä kuvauksia jokaisesta toimituksesta versionhallintajärjestelmässä, kuten Git. Kun teet muutoksia projektitiedostoihisi, sinun tulee antaa viesti, jossa selitetään, mitä ne tekevät tai miksi teit ne.

Commit-viestit toimivat dokumentointi- ja viestintämuotona. Niillä on ratkaiseva rooli projektin selkeän ja organisoidun versiohistorian ylläpitämisessä. Opi kirjoittamaan hyviä sitoutumisviestejä ja muut tiimisi jäsenet arvostavat työtäsi entistä enemmän.

Hyvän sitoutumisviestin rakenne

Hyvä esimerkki toimitusviestistä sisältää neljä osaa: tyyppi, kuvaus, teksti ja alatunniste.

Niin kuin:

: 
[valinnainen runko]
[valinnainen alatunniste]

Tyyppi

Tyyppi kuvaa nykyisessä sitoumuksessa tehdyn muutoksen tyyppiä. Voit käyttää mitä tahansa järjestelmää, joka sopii olosuhteisiisi. Tässä on esimerkiksi muutamia esimerkkiavainsanoja, joilla voit ilmoittaa kunkin tyyppisestä muutoksesta esimerkkikäytön ohella:

• feat: tekemäsi muutokset tuovat uuden ominaisuuden.
• korjata: korjaat bugin.
• uudelleentekijä: muutoksesi heijastaa koodia korjaamatta virhettä tai lisäämättä uutta ominaisuutta.
• testata: teet kaikki testaukseen liittyvät muutokset. Esimerkiksi kun sinä kirjoittaa testejä Jestin kanssa tai mikä tahansa muu testauskehys sinä valitset.
• urakka: muutokset, jotka eivät liity korjaukseen, ominaisuuteen tai testiin. Esimerkiksi riippuvuuksien päivittäminen.
• asiakirjoja: kun päivität asiakirjoja.
• tyyli: muutokset, jotka eivät vaikuta koodin merkitykseen, kuten välilyöntien lisääminen, puuttuvat puolipisteet jne.
• perf: suorituskyvyn parannuksiin liittyvät muutokset.
• rakentaa: kun teet muutoksia, jotka vaikuttavat koontitiedostoihin.
• ci: jatkuvaan integraatioon liittyvät muutokset.
• palautua: kun palataan edelliseen sitoumukseen.

Kuvaus

Toimitusviestin "kuvaus" on ytimekäs ja kuvaava yhteenveto sitoumuksessa tehdyistä muutoksista. Se toimii otsikkona, joka vangitsee sitoumuksen olemuksen.

Kun kirjoitat kuvausta, muista seuraavat asiat:

• Tee siitä riittävän selkeä ja täsmällinen kuvaillaksesi sitoumusta yhdellä silmäyksellä.
• Tee se lyhyesti ja ytimekkäästi. Ihannetapauksessa sen rajoittaminen 50 merkkiin tai vähemmän olisi parasta.
• Kirjoita se nykymuodossa, vaikka kuvaisit jo tehtyjä muutoksia.
• Käytä pakottavaa tunnelmaa kirjoittaessasi sitä.
• Aloita isolla kirjaimella.
• Älä lopeta sitä pisteellä.

Esimerkiksi:

feat: Ota käyttöön tumma tila kotisivulle

Tämä esimerkki näyttää, kuinka voit kirjoittaa kuvauksen sitoutumiselle toteuttaa pimeän tilan. Se käyttää feat tyyppiä, koska se tuo uuden ominaisuuden.

Runko (valinnainen)

Toimitusviestin tekstiosa sisältää lisätietoja ja kontekstin vahvistukseen tehdyistä muutoksista. Et aina tarvitse runkoa, mutta se voi auttaa tarjoamaan lisätietoja, selittämään muutoksen perustelut tai kuvailemaan teknisiä näkökohtia.

Tässä on muutamia huomioitavia asioita, kun kirjoitat toimitusviestin tekstiosaa:

• Git ei koskaan rivitä tekstiä automaattisesti, joten rivitä se manuaalisesti 72 merkin pituiseksi, kun kirjoitat tekstin. Tämä antaa Gitille tarpeeksi tilaa tekstin sisentämiseen, mikä tekee siitä luettavamman.
• Käytä kehoa selittääksesi, mitä muutoksessa tapahtui, miksi teit muutoksen ja perustelut muutoksesi taustalla.
• Sinun on jätettävä tyhjä rivi kuvausrivin ja tekstin väliin. Näin Git pystyy erottamaan ne toisistaan.
• Jos sitoumus tuo mukanaan useita muutoksia tai vaikuttaa koodikannan eri osiin, harkitse luettelomerkkien tai kappaleiden käyttöä muutosten purkamiseen. Tämä parantaa luettavuutta ja auttaa lukijoita ymmärtämään sitoumuksen eri puolia.

Esimerkiksi:

feat: Lisää GitHub OAuth-palveluntarjoajaksi
Integroi GitHub OAuth-palveluntarjoajaksi mahdollistaaksesi saumattoman 
todennus GitHub-tileillä.
- Ota käyttöön OAuth-todennuskulku GitHub API: lla
- Määritä tarvittavat päätepisteet ja asetukset GitHub-todennusta varten
- Päivitä käyttöliittymä lisäämään GitHub-kirjautumisvaihtoehto

Yllä oleva esimerkki näyttää hyvän Git-sitoutumisviestin ominaisuudelle, joka lisää GitHub OAuth-palveluntarjoajana hakemuksellesi. Tässä vahvistusviestissä on ytimekäs tiivistelarivi (enintään 50 merkkiä), yksityiskohtaisempi selittävä teksti (rivitetty noin 72 merkkiin) ja luettelomerkit lisätietoja varten.

Toimitusviestin alatunnisteosa on valinnainen osa, joka tarjoaa toimitukseen liittyviä lisätietoja tai metatietoja. Se sijoitetaan yleensä runko-osan jälkeen tyhjällä viivalla erotettuna. Alatunniste voi sisältää erilaisia ​​tietoja, kuten viittauksia aiheeseen liittyviin ongelmiin, tunnisteita tai erityisiä huomautuksia.

Kun viittaat ongelmiin, vetopyyntöihin tai muihin aiheeseen liittyviin kohteisiin, käytä projektisi ongelmanseurantajärjestelmän edellyttämää asianmukaista syntaksia tai muotoa. Tämä varmistaa, että viittaukset tunnistetaan ja linkitetään oikein.

Esimerkiksi:

feat: Lisää GitHub OAuth-palveluntarjoajaksi
Integroi GitHub OAuth-palveluntarjoajaksi mahdollistaaksesi saumattoman 
todennus GitHub-tileillä.
- Ota käyttöön OAuth-todennuskulku GitHub API: lla
- Määritä tarvittavat päätepisteet ja asetukset GitHub-todennusta varten
- Päivitä käyttöliittymä lisäämään GitHub-kirjautumisvaihtoehto
Ratkaisu: #123
Katso myös: #456, #789

Alatunniste viittaa asiaan liittyvään ongelmaan #123 ja mainitsee muut aiheeseen liittyvät ongelmat #456 ja #789 lisäkontekstia varten.

Sitoutusviestin lisääminen

Voit kirjoittaa sitoutumisviestejä käyttämällä -m lippu ja sen jälkeen vahvistusviesti lainausmerkeissä (valinnainen mutta suositeltavaa).

The -m lippu on ihanteellinen lyhyille vahvistusviesteille, jotka sisältävät yleensä tyypin ja kuvauksen.

Esimerkiksi:

git commit -m "chore: Vaihda linteri ESlintiksi"

Kuitenkin, kun toimitusviestisi vaatii enemmän yksityiskohtia, kuten tekstin ja alatunnisteen, sinun on parempi kirjoittaa vahvistus tekstieditorissa tai IDE: ssä.

Vaihtoehtoisesti voit kirjoittaa pitkiä vahvistusviestejä tekstitiedostoon ja käyttää --tiedosto lippu määrittääksesi toimitusviestit tekstitiedoston sisällöksi.

Esimerkiksi:

git commit --tiedosto commit_message.txt

Kun suoritat yllä olevan komennon, git käyttää tiedoston sisältöä vahvistusviestinä.

Voit myös käskeä gitiä avaamaan oletuseditorin kirjoittaaksesi pidemmän viestin. Jos sinulla on GIT_EDITOR tai EDITOR ympäristömuuttuja asetettu, git avaa kyseisen ohjelman, kun suoritat paljaan git commit komento.

Miksi sinun pitäisi kirjoittaa hyviä sitoutumisviestejä

Hyvien sitoumusviestien kirjoittaminen on ratkaisevan tärkeää tehokkaan yhteistyön ja koodin ylläpidon kannalta. Selkeät ja kuvaavat viestit auttavat ymmärtämään, korjaamaan ja tarkistamaan koodia. He voivat jopa osallistua projektidokumentaatioon tai julkaisutietoihin.

Ne mahdollistavat tiedon jakamisen, sujuvan käyttöönoton ja tukevat versionhallintaa. Laadukkaiden toimitusviestien priorisointi tehostaa kehitysprosesseja ja varmistaa koodikannan ylläpidettävyyden.