Git Commit -viestin kirjoittaminen

Sisältö: Sisältö: Johdanto | Seitsemän sääntöä | Vinkkejä

Esittely:

Jos selaat minkä tahansa satunnaisen Git-tietovaraston lokia, huomaat todennäköisesti, että sen commit-viestit ovat enemmän tai vähemmän sekaisin. Vilkaise esimerkiksi näitä helmiä varhaisilta päiviltäni, jolloin komitin Springiä:

$ git log --oneline -5 --author cbeams --before "Fri Mar 26 2009"e5f4b49 Re-adding ConfigurationPostProcessorTests after its brief removal in r814. @Ignore-ing the testCglibClassesAreLoadedJustInTimeForEnhancement() method as it turns out this was one of the culprits in the recent build breakage. The classloader hacking causes subtle downstream effects, breaking unrelated tests. The test method is still useful, but should only be run on a manual basis to ensure CGLIB is not prematurely classloaded, and should not be run as part of the automated build.2db0f12 fixed two build-breaking issues: + reverted ClassMetadataReadingVisitor to revision 794 + eliminated ConfigurationPostProcessorTests until further investigation determines why it causes downstream tests to fail (such as the seemingly unrelated ClassPathXmlApplicationContextTests)147709f Tweaks to package-info.java files22b25e0 Consolidated Util and MutableAnnotationUtils classes into existing AsmUtils7f96f57 polishing

Yikes. Vertaa sitä näihin uudempiin kommitointeihin samasta arkistosta:

$ git log --oneline -5 --author pwebb --before "Sat Aug 30 2014"5ba3db6 Fix failing CompositePropertySourceTests84564a0 Rework @PropertySource early parsing logice142fd1 Add tests for ImportSelector meta-data887815f Update docbook dependency and generate epubac8326d Polish mockito usage

Kumman lukisit mieluummin?

Ensimmäinen vaihtelee pituudeltaan ja muodoltaan; jälkimmäinen on ytimekäs ja johdonmukainen.
Ensimmäinen tapahtuu oletusarvoisesti; jälkimmäinen ei koskaan tapahdu vahingossa.

Vaikkakin monien arkistojen lokit muistuttavat ensiksi mainittua tapaa, on olemassa myös poikkeuksia. Linux-ydin ja itse Git ovat hyviä esimerkkejä. Katso vaikka Spring Bootia tai mitä tahansa Tim Popen hallinnoimaa arkistoa.

Näiden arkistojen tekijät tietävät, että hyvin laadittu Git-toimitusviesti on paras tapa välittää muutosta koskeva asiayhteys muille kehittäjille (ja itse asiassa heidän tuleville itselleen). Diff kertoo, mikä muuttui, mutta vain commit-viesti voi kertoa kunnolla miksi. Peter Hutterer tuo tämän pointin hyvin esille:

Koodin kontekstin palauttaminen on tuhlausta. Emme voi välttää sitä kokonaan, joten ponnistelujemme tulisi kohdistua sen vähentämiseen niin paljon kuin mahdollista. Commit-viesteillä voidaan tehdä juuri näin, ja sen seurauksena commit-viesti osoittaa, onko kehittäjä hyvä yhteistyökumppani.

Jos et ole miettinyt kovinkaan paljon sitä, millainen on hyvä Gitin commit-viesti, voi olla, ettet ole viettänyt paljon aikaa git log:n ja siihen liittyvien työkalujen käytössä. Tässä on noidankehä: koska commit-historia on jäsentymätön ja epäjohdonmukainen, sitä ei käytetä paljon aikaa sen käyttämiseen tai siitä huolehtimiseen. Ja koska sitä ei käytetä tai hoideta, se pysyy jäsentymättömänä ja epäjohdonmukaisena.

Mutta hyvin hoidettu loki on kaunis ja hyödyllinen asia. git blame, revert, rebase, log, shortlog ja muut alakäskyt heräävät henkiin. Muiden kommittien ja pull requestien tarkistamisesta tulee jotain tekemisen arvoista, ja yhtäkkiä sen voi tehdä itsenäisesti. Sen ymmärtämisestä, miksi jokin tapahtui kuukausia tai vuosia sitten, tulee paitsi mahdollista myös tehokasta.

Projektin pitkän aikavälin menestys riippuu (muun muassa) sen ylläpidettävyydestä, ja ylläpitäjällä on vain harvat työkalut, jotka ovat tehokkaampia kuin projektinsa loki. Kannattaa käyttää aikaa siihen, että oppii hoitamaan sitä oikein. Se, mikä aluksi saattaa olla vaivalloista, muuttuu pian tavaksi ja lopulta ylpeyden ja tuottavuuden lähteeksi kaikille asianosaisille.

Tässä kirjoituksessa käsittelen vain perustavanlaatuisinta osaa terveen komitointihistorian ylläpidosta: miten kirjoittaa yksittäinen komitointiviesti. On muitakin tärkeitä käytäntöjä, kuten commit squashing, joita en käsittele tässä. Ehkä teen sen myöhemmässä postauksessa.

Useimmilla ohjelmointikielillä on vakiintuneet konventiot siitä, mikä on idiomaattinen tyyli, eli nimeäminen, muotoilu ja niin edelleen. Näistä konventioista on tietysti olemassa variaatioita, mutta useimmat kehittäjät ovat yhtä mieltä siitä, että yhden valitseminen ja siitä kiinni pitäminen on paljon parempi kuin kaaos, joka syntyy, kun kaikki tekevät omia juttujaan.

Tiimin lähestymistavan sitoutumislokiinsa ei pitäisi olla erilainen. Käyttökelpoisen versiohistorian luomiseksi tiimien tulisi ensin sopia commit-viestien konventiosta, joka määrittelee ainakin seuraavat kolme asiaa:

Tyyli. Merkintäsyntaksi, wrap-marginaalit, kielioppi, suuraakkoset, välimerkit. Kirjoita nämä asiat tarkasti, poista arvailut ja tee kaikesta mahdollisimman yksinkertaista. Lopputuloksena on huomattavan johdonmukainen loki, jota ei ole vain ilo lukea, vaan jota todella luetaan säännöllisesti.

Sisältö. Millaista tietoa commit-viestin rungon (jos sellainen on) tulisi sisältää? Mitä sen ei pitäisi sisältää?

Metatiedot. Miten ongelmien seurantatunnuksiin, pull request -numeroihin jne. tulisi viitata?

Onneksi on olemassa vakiintuneita konventioita siitä, millainen on idiomaattinen Git-toimitusviesti. Itse asiassa monet niistä oletetaan tiettyjen Git-komentojen toimintatavassa. Mitään ei tarvitse keksiä uudelleen. Noudata vain alla olevia seitsemää sääntöä, ja olet matkalla tekemään komennuksia kuin ammattilainen.

Hyvän Git-komennusviestin seitsemän sääntöä

Pitäkää mielessä: Tämä kaikki on sanottu ennenkin.

1. Erottele aihe ja runko tyhjällä rivillä
2. Limita aiherivi 50 merkkiin
3. Kirjoita aiherivi isolla alkukirjaimella
4. Älä päätä aiheriviä pisteeseen
5. Käytä imperatiivin mielialaa aiherivissä
6. Kierrä runko 72 merkkiin
7. Käytä rungon selittämiseen, mitä tapahtuu, ja siihen, miksi vast. miten

Esimerkiksi:

Summarize changes in around 50 characters or lessMore detailed explanatory text, if necessary. Wrap it to about 72characters or so. In some contexts, the first line is treated as thesubject of the commit and the rest of the text as the body. Theblank line separating the summary from the body is critical (unlessyou omit the body entirely); various tools like `log`, `shortlog`and `rebase` can get confused if you run the two together.Explain the problem that this commit is solving. Focus on why youare making this change as opposed to how (the code explains that).Are there side effects or other unintuitive consequences of thischange? Here's the place to explain them.Further paragraphs come after blank lines. - Bullet points are okay, too - Typically a hyphen or asterisk is used for the bullet, preceded by a single space, with blank lines in between, but conventions vary hereIf you use an issue tracker, put references to them at the bottom,like this:Resolves: #123See also: #456, #789

Erottele aihe ja runko tyhjällä rivillä

Lähteestä git commit manpage:

Vaikkei se olekaan pakollista, on hyvä ajatus aloittaa komitointiviesti yhdellä lyhyellä (alle 50-merkkisellä) rivillä, jossa on yhteenveto muutoksesta, jota seuraa tyhjä rivi ja sen jälkeen perusteellisempi kuvaus. Sitoumusviestin ensimmäiseen tyhjään riviin asti olevaa tekstiä käsitellään sitoumuksen otsikkona, ja tätä otsikkoa käytetään koko Gitissä. Esimerkiksi Git-format-patch(1) muuttaa toimituksen sähköpostiksi, ja se käyttää otsikkoa otsikkorivillä ja loput toimituksesta rungossa.

Ensiksikin, kaikki toimitukset eivät vaadi sekä otsikkoa että runkoa. Joskus yksi rivi riittää, varsinkin kun muutos on niin yksinkertainen, ettei muuta kontekstia tarvita. Esimerkiksi:

Fix typo in introduction to user guide

Muuta ei tarvitse sanoa; jos lukija ihmettelee, mikä kirjoitusvirhe oli, hän voi yksinkertaisesti katsoa itse muutosta, eli käyttää git show tai git diff tai git log -p.

Jos toimitat jotain tällaista komentorivillä, on helppoa käyttää -m-vaihtoehtoa git commit:

$ git commit -m"Fix typo in introduction to user guide"

Mutta kun toimitus ansaitsee hieman selitystä ja asiayhteyttä, sinun on kirjoitettava runko. Esimerkiksi:

Derezz the master control programMCP turned out to be evil and had become intent on world domination.This commit throws Tron's disc into MCP (causing its deresolution)and turns it back into a chess game.

Commit-viestejä, joissa on body, ei ole niin helppo kirjoittaa -m-optiolla. Sinun on parempi kirjoittaa viesti kunnon tekstieditorilla. Jos sinulla ei vielä ole editoria, jota voit käyttää Gitin kanssa komentorivillä, lue tämä Pro Git -kirjan osa.

Joka tapauksessa aiheen ja rungon erottaminen toisistaan kannattaa lokia selatessa. Tässä on koko lokimerkintä:

$ git logcommit 42e769bdf4894310333942ffc5a15151222a87beAuthor: Kevin Flynn <[email protected]>Date: Fri Jan 01 00:00:00 1982 -0200 Derezz the master control program MCP turned out to be evil and had become intent on world domination. This commit throws Tron's disc into MCP (causing its deresolution) and turns it back into a chess game.

Ja nyt git log --oneline, joka tulostaa vain otsikkorivin:

$ git log --oneline42e769 Derezz the master control program

Od, git shortlog, joka ryhmittelee komennukset käyttäjäkohtaisesti, näyttäen taas vain otsikkorivin ytimekkyyden vuoksi:

$ git shortlogKevin Flynn (1): Derezz the master control programAlan Bradley (1): Introduce security program "Tron"Ed Dillinger (3): Rename chess program to "MCP" Modify chess program Upgrade chess programWalter Gibbs (1): Introduce protoype chess program

Gitissä on useita muitakin konteksteja, joissa otsikkorivin ja rungon erottaminen potkaisee – mutta yksikään niistä ei toimi kunnolla ilman tyhjää riviä välissä.

Limitoi otsikkorivi 50 merkkiin

50 merkkiä ei ole kova raja, vain nyrkkisääntö. Tämän pituisten otsikkorivien pitäminen varmistaa niiden luettavuuden ja pakottaa kirjoittajan miettimään hetken aikaa, mikä olisi ytimekkäin tapa selittää, mistä on kyse.

Vinkki: Jos yhteenvedon tekeminen on vaikeaa, saatat tehdä liian monta muutosta kerralla. Pyri atomisiin kommitointeihin (aihe erilliselle postaukselle).

GitHubin käyttöliittymä on täysin tietoinen näistä konventioista. Se varoittaa sinua, jos ylität 50 merkin rajan:

Ja katkaisee kaikki yli 72 merkkiä pitkät otsikkorivit ellipsillä:

Siirrä siis 50 merkkiä, mutta pidä 72 merkkiä kovana raja-arvona.

Kirjoita isolla alkukirjaimella otsikkoriville

Tämä on niin yksinkertaista kuin miltä kuulostaa. Aloita kaikki otsikkorivit isolla alkukirjaimella.

Esimerkiksi:

• Kiihdytä nopeuteen 88 mailia tunnissa

Ei esimerkiksi:

• kiihdytä nopeuteen 88 mailia tunnissa

Älä päätä otsikkoriviä pisteeseen

Viimeistelemällä tehtävät välimerkit ovat turhia otsikkoriveissä. Sitä paitsi tila on kallisarvoista, kun ne pyritään pitämään enintään 50 merkissä.

Esimerkki:

• Open the pod bay doors

Instead of:

• Open the pod bay doors.

Käytä imperatiivista mielialaa otsikkorivillä

Imperatiivinen mieliala tarkoittaa vain ”puhuttu tai kirjoitettu ikään kuin käskyä tai ohjetta antaen”. Muutamia esimerkkejä:

• Puhdista huoneesi
• Sulje ovi
• Vie roskat ulos

Jokainen niistä seitsemästä säännöstä, joista luet juuri nyt, on kirjoitettu imperatiivissa (”Kääri runko 72 merkin kohdalla” jne.).

Imperatiivi voi kuulostaa hieman epäkohteliaalta; siksi emme usein käytä sitä. Mutta se sopii täydellisesti Git-komission aiheisiin. Yksi syy tähän on se, että Git itse käyttää imperatiivia aina, kun se luo commitin puolestasi.

Esimerkiksi oletusviesti, joka luodaan käytettäessä git merge, kuuluu:

Merge branch 'myfeature'

Ja käytettäessä git revert:

Revert "Add the thing with the stuff"This reverts commit cc87791524aedd593cff5a74532befe7ab69ce9d.

Od tai napsauttaessasi ”Merge”-painiketta GitHubin pull requestissa:

Merge pull request #123 from someuser/somebranch

Kirjoittaessasi commit-viestejä imperatiivilla noudatat siis Gitin omia sisäänrakennettuja konventioita. Esimerkiksi:

• Refactor subsystem X for readability
• Update getting started documentation
• Remove deprecated methods
• Release version 1.0.0

Kirjoittaminen tällä tavalla voi olla aluksi hieman hankalaa. Olemme tottuneet puhumaan enemmän indikatiivissa, jossa on kyse tosiasioiden ilmoittamisesta. Siksi commit-viestit päätyvät usein lukemaan näin:

• Fixed bug with Y
• Changing behavior of X

Ja joskus commit-viestit kirjoitetaan kuvauksena niiden sisällöstä:

• Lisää korjauksia rikki menneisiin juttuihin
• Makeat uudet API-metodit

Sekaannusten poistamiseksi tässä on yksinkertainen sääntö, jonka avulla se onnistuu joka kerta.

Oikein muotoillun Git-toimituksen otsikkorivin pitäisi aina pystyä täydentämään seuraava lause:

• Jos sitä sovelletaan, tämä toimeksianto tulee otsikkorivisi tänne

Esimerkiksi:

• Jos sitä sovelletaan, tämä komento refaktoroi osajärjestelmää X luettavuuden parantamiseksi
• Jos sitä sovelletaan, tämä komento päivittää aloitusdokumentaation
• Jos sitä sovelletaan, tämä komento poistaa vanhentuneet metodit
• Jos sitä sovelletaan, tämä komento julkaisee version 1.0.0
• Jos sitä sovelletaan, tämä sitoumus sulauttaa käyttäjän/branchin pull request #123

Huomaa, että tämä ei toimi muiden kuin imperatiivisten muotojen kohdalla:

• Jos sitä sovelletaan, tämä commit korjaa Y:n bugin
• Jos sitä sovelletaan, tämä commit muuttaa X:n käyttäytymistä
• Jos sitä sovelletaan, tämä commit lisää korjauksia rikkinäisiin asioihin
• Jos sitä sovelletaan, tämä commit sulostuttaa uusia API-metodeja

Muistakaa: Imperatiivin käyttö on tärkeää vain otsikkorivillä. Voit höllentää tätä rajoitusta kirjoittaessasi runkoa.

Kääri runko 72 merkkiin

Git ei koskaan kääri tekstiä automaattisesti. Kun kirjoitat commit-viestin runkoa, sinun on pidettävä huolta sen oikeasta marginaalista ja paketoitava teksti manuaalisesti.

Suositus on tehdä tämä 72 merkin kohdalla, jotta Gitillä on runsaasti tilaa tekstin sisennyksille ja silti kaikki pysyy alle 80 merkin kokonaispituudessa.

Hyvä tekstieditori voi auttaa tässä. Esimerkiksi Vim on helppo konfiguroida niin, että se kietoo tekstin 72 merkkiin, kun kirjoitat Git-toimitusta. Perinteisesti IDE:t ovat kuitenkin olleet surkeita tarjoamaan älykästä tukea tekstin käärimiselle commit-viesteissä (vaikkakin viimeisimmissä versioissa IntelliJ IDEA on vihdoin parantanut tätä).

Käytä runkoa selittämään mitä ja miksi vs. miten

Tämä Bitcoin Coresta tehty commit on loistava esimerkki siitä, miten selitetään, mikä muuttui ja miksi:

commit eb0b56b19017ab5c16c745e6da39c53126924ed6Author: Pieter Wuille <[email protected]>Date: Fri Aug 1 22:57:55 2014 +0200 Simplify serialize.h's exception handling Remove the 'state' and 'exceptmask' from serialize.h's stream implementations, as well as related methods. As exceptmask always included 'failbit', and setstate was always called with bits = failbit, all it did was immediately raise an exception. Get rid of those variables, and replace the setstate with direct exception throwing (which also removes some dead code). As a result, good() is never reached after a failure (there are only 2 calls, one of which is in tests), and can just be replaced by !eof(). fail(), clear(n) and exceptions() are just never called. Delete them.

Katso koko diff ja mieti, kuinka paljon aikaa kirjoittaja säästää muiden ja tulevien committereiden aikaa, kun hän käyttää aikaa tämän kontekstin tarjoamiseen tässä ja nyt. Jos hän ei tekisi niin, se olisi luultavasti kadonnut ikuisiksi ajoiksi.

Useimmissa tapauksissa voit jättää pois yksityiskohdat siitä, miten muutos on tehty. Koodi on tässä suhteessa yleensä itsestään selvä (ja jos koodi on niin monimutkaista, että se pitää selittää proosassa, sitä varten on lähdekommentit). Keskity vain tekemään selväksi syyt, miksi ylipäätään teit muutoksen – miten asiat toimivat ennen muutosta (ja mikä siinä oli vikana), miten ne toimivat nyt ja miksi päätit ratkaista asian juuri tällä tavalla.

Tulevaisuuden ylläpitäjä, joka kiittää sinua, saatat olla sinä itse!

Vinkkejä

Opi rakastamaan komentoriviä. Jätä IDE taaksesi.

Niin monesta syystä kuin on olemassa Git-alikomentoja, on viisasta omaksua komentorivi. Git on mielettömän tehokas; IDE:t ovat myös, mutta kumpikin eri tavoin. Käytän IDE:tä joka päivä (IntelliJ IDEA) ja olen käyttänyt muita laajasti (Eclipse), mutta en ole koskaan nähnyt IDE:n integraatiota Git:iin, joka voisi alkuunkaan vetää vertoja komentorivin helppoudelle ja teholle (kunhan sen tuntee).

Tietyt Git:iin liittyvät IDE:n funktiot ovat korvaamattomia, kuten git rm:n kutsuminen tiedostoa poistettaessa ja oikeiden toimien tekeminen git:llä tiedoston uudelleennimeämisessä. Kaikki hajoaa, kun alat yrittää commitata, sulauttaa, rebasea tai tehdä kehittynyttä historia-analyysiä IDE:n kautta.

Kun on kyse Gitin täyden tehon käyttämisestä, se on komentorivillä koko matkan.

Muista, että riippumatta siitä, käytätkö Bashia, Zsh:ta vai Powershelliä, on olemassa välilehtien täydennysskriptejä, jotka vievät paljon vaivaa alakomentojen ja kytkimien muistamisesta.

Lue Pro Git

Pro Git -kirja on saatavana netistä ilmaiseksi, ja se on fantastinen. Hyödynnä!

otsikon kuvan luotto: xkcd