Gerrit Code Review
Denna artikel beskriver hur man använder Gerrit Code Review. Hur man administrerar sina repos utan granskningsfunktionen i Gerrit står beskrivet här.
Introduktion
Gerrit fyller främst två funktioner:
- Administrera repo- & projekt-rättigheter
- Support för granskning av commits innan dom mergas in i repot
Istället för att pusha commits direkt till t.ex. master, så pushar man till en fiktiv granskningsbranch som heter for/master. Eftersom en commit kan underkännas och kräver justering innan acceptering, så använder Gerrit ett Change-Id i commit meddelandet för att koppla ihop dessa till samma ändring. Nya commits med samma Change-Id blir nya s.k. patch sets i Gerrit. Commits som har olika Change-Ids behandlas som helt olika förändringar. Det går även att ställa in så man har rättighet att pusha direkt till master (eller annan) branch. Man går då förbi granskningsdelen i Gerrit. Om man behåller granskningsfunktionen i Gerrit, måste varje commit granskas och verifieras innan den kan kan submittas till t.ex. master i repositoryt. Gerri använder ett poängsystem där verifiering +1 betyder ok, och -1 betyder att committen underkändes. För granskning kan -2 till +2 poäng sättas. -1 till +1 betyder rekommendationer. -2 betyder att committen underkänds och +2 betyder att den kan accepteras.
Gerrit stödjer också olika policies när en commit får submittas till t.ex. master branchen. Gerrit kan tillåta att den måste göra triviala mergningar, men man kan också vara sträng och kräva att committen baseras på den senaste committen som redan finns i repot (s.k. fast-forward). Följande policies existerar:
- Fast-forward only
- Merge if necessary
- Always merge
- Cherry-pick
Komma igång
Gerrits webinterface körs oftast på port 8080 och git kommandona över ssh körs oftast på port 29418. För att komma igång med Gerrit, så behöver du ett konto samt ladda upp din publika del av en SSH nyckel. Om du inte redan har ett SSH nyckelpar, skapa ett via kommandot ssh-keygen. För att skapa en RSA nyckel, kör kommandot:
Om du inte vill skydda nyckeln med ett lösenord, tryck bara på enter när lösenord efterfrågas.
Logga in på Gerrit. Gå till Settings och SSH Public Keys. Ladda upp din publika nyckel, dvs ofta innehållet i filen ~/.ssh/id_rsa.pub om du skapade en RSA nyckel enligt ovan.
För att testa din nyckel, kör följande kommando:
Om allt går bra ska du se en hälsningsfras liknande:
**** Welcome to Gerrit Code Review **** Hi, you have successfully connected over SSH. Unfortunately, interactive shells are disabled. To clone a hosted Git repository, use: git clone ssh://USER@HOST:29418/REPOSITORY_NAME.git Connection to HOST closed.
Klona ett repo
Normalt sett behöver man bara klona ett repo en gång. Man får då tillgång till alla version av repot. För att sen uppdatera sin klon använder man git pull eller git fetch. Exempel: Klona ett repo som heter helloworld:
Kopiera Change-Id Commit Hook från Gerrit
För att automatiskt generera och lägga till ett Change-Id till commit-meddelandet. Kopiera en commit-hook ifrån Gerrit. Gå till root-katalogen i ditt klonade repo och kör kommandot:
Detta behöver bara göras en gång efter att du klonat ett repo.
Pusha en commit till master för granskning
Innan du pushar ditt resultat så måste ändringarna vara squashade till en commit, och beroende på regler i Gerrit, ha ett Change-Id i commit meddelandet och ev. vara baserad på senaste commiten som finns på master branchen. Mer om detta hur man jobbar i Git.
När dina förändringar du gjort på en lokal branch är klara, så pushar du dom från din branch till master via kommandot:
Om allt gått bra så ska din push synas i Gerrit.
Efter att din commit granskats och testats, kan den publiceras från Gerrit och först då är den verkligen inne på master branchen i repot i Gerrit. Refspecen for/master är en fiktiv branch i Gerrit dit alla pushar sina commits som ska till master branchen. Se det som en kö, fast man behöver inte följa ordningen. Den som blivit granskad först blir också den som mergas till master först.
Scenarion
Detta kapitel kommer beskriva några scenarion med Gerrit där ett projekt har följande inställningar:
- Fast-forward only
- Change-Id krävs i varje commit
- Ett Jenkins jobb sköter verifieringen
- URL:en till projektet är ssh://192.168.0.10:29418/helloworld.git
Scenario: Utveckla på branch. Pusha till master
Klona projektet och skapa en branch som t.ex. heter test:
(Hur man klonar projektet kommer utelämnas i övriga exempel) Skapa och byt till en branch som heter main-args:
Genomför ändringarna. I detta exempel så ändrar vi funktionen main() i första commit:en att ta input argument (argc & argv). I andra commit:en fixar vi till vår Makefil så vi slipper se varning om oanvända input argument. Vi har nu två commits på vår branch med olika Change-Ids:
commit 31bce6515687786e9cb39a022ff83f715f9a8758
Author: Peter Kerwien <peter@kerwien.homeip.net>
Date: Sat May 11 18:49:54 2013 +0200
Silent unused parameter warning.
Change-Id: I3de2beeb504a55d0a76e7cbc16f80811a8e35ad6
commit 4eb3343939271ed28f2509a1f6910e9aaba00d21
Author: Peter Kerwien <peter@kerwien.homeip.net>
Date: Sat May 11 18:36:22 2013 +0200
Added arguments to main() function.
Change-Id: I275a3095dd5deb0ae38a82b0c071c22d74e16d91
För att squash:a våra commit:s så skapar vi en ny branch som vi döper till main-args-squash:
Merge:a från main-args och squash:a ihop till en commit:
Nu kan vi push:a till for/master i Gerrit för granskning:
I Gerrit finns nu följande patch set att granska:
Då vi saknar andra användare i dessa exempel, kommer vi själva att granska vår kod. Tryck på Review-knappen. Godkänd ändringarna genom att ange +2 poäng och tryck på Publish and Submit-knappen för att publicera granskningen samt pusha till master branch:en:
Vår ändringar är nu commit:ade till master branchen i repo:t:
Scenario: Rätta underkänd verifiering eller granskning
Anta att du har push:at dina ändringar till for/master i Gerrit, men koden godkänns inte utan måste rättas till. I detta exempel har vi gjort en förändring på en branch som heter hello-msg. Vi har ändrat vårt "Hello, world!" meddelande till "Hello, gerrit!" och push:at till Gerrit. Tyvärr så kommer denna förändring inte igenom granskningen då någon underkänner våra förändringar:
Granskaren angav kommentaren att meddelandet ska ändras till "Hello, git!" istället. Gå tillbaka till ditt repo. Vi skulle nu kunna förändra innehållet i vår commit och sen push:a till Gerrit igen. Men vi väljer att göra en helt ny commit på vår hello-msg branch:
commit ea03d97f419ba918a147363106b2326b42656707
Author: Peter Kerwien <peter@kerwien.homeip.net>
Date: Sat May 11 19:36:29 2013 +0200
Change to Hello, git
Change-Id: I3d89419b668d4a76963a30a4c68cdec67cc8fe58
commit 68a26d71ea697bf7097a0e1fafe39ca246266a9f
Author: Peter Kerwien <peter@kerwien.homeip.net>
Date: Sat May 11 19:23:25 2013 +0200
Change to Hello, gerrit
Change-Id: I67eb8745523c70ced32c531e132cd421885dfb47
Men för att kunna push:a upp rättningen, så måste vi squash:a ihop dessa commit:s till en. Vi kan göra som i exemplet ovan och göra det på en ny branch som vi kallar för hello-msg-squash. Efter att vi skapat vår squash:ade commit, måste vi dock ändra Change-Id till samma som vår första commit hade som vi pushade till Gerrit. Detta för att Gerrit ska hålla ihop dessa och skapa ett nytt patch set. Ändra Change-Id till I67eb8745523c70ced32c531e132cd421885dfb47 med kommandot:
Nu kan vi push:a till for/master igen:
I Gerrit har nu ett nytt patch set skapats:
Nu kan patch set 2 granskas och godkännas. När detta är gjort kan våra förändringar push:as till master genom att trycka på Submit patch set 2-knappen:
Scenario: Rebase innan submit till master
Då vårt projekt kräver fast-forward, så måste varje patch set baseras på senaste commit:en på master innan de kan accepteras. Anta att vi gjort en ändring på en branch som heter opt-build som vi har pushat till Gerrit för granskning. Men innan vår commit godkänns, så hinner en annan commit komma in på master. Vi kommer då se följande när vi försöker submit:a i Gerrit:
Gå tillbaka till repositoryt och börja med att uppdatera din master:
Byt sedan tillbaka till opt-build och rebase:a:
Vår commit har nu förändrats, men dess commit-meddelande och därmed också Change-Id är intakt. Vi kan därför direkt push:a till Gerrit och skapa ett patch set 2:
Nu kan våra ändringar godkännas och submit:as till master:
