Brussels, 02. - 03.02.2013

Using Gerrit Code Review

in an

Open Source Project

License: CC BY-SA 3.0

(pictures of other authors excluded)

1

Brussels, 02. - 03.02.2013

Contents of this talk

• Gerrit is a

• Web-based code review tool

• Git server

• Using Gerrit in the TYPO3 project

• Large PHP community

• Experience of the last 2.5 years

2

Brussels, 02. - 03.02.2013

Steffen Gebert

• TYPO3 CMS Core Team Member(2010-2012)

• TYPO3 Server Admin Team Member(since 2011)

• PhD Student in Computer Science(Communication Networks, since 2011)

• E-Mail: steffen.gebert@typo3.orgTwitter: @StGebert

3

I’m not affiliated with Gerrit or Google. Just a happy user (and contributor of 4 tiny patches)

Brussels, 02. - 03.02.2013

Questions!

• Happy to answeryour questions!

• Come down hereafter the talk!

Foto “Question mark”: Yello-Doghttp://www.sxc.hu/photo/1279316

• Slides availablehttp://slideshare.net/stephenking/

4

comments included!

nice that you found the slides - have fun ☺

Brussels, 02. - 03.02.2013

Motivation for Code Reviews

• Who writes bug-free code?

• Who knows all best-practices of programming?

• Review changes of friends and contributors!

• Keep bad code out of your repository

• Learn from others

Based on a photo by CMSeterhttp://www.sxc.hu/photo/1062451

5

“Every change has to be reviewed by at least two other persons”

Example Policy:

With Gerrit you can actually enforce these policies, also for team members.

Brussels, 02. - 03.02.2013

Using

Gerrit Code Review

6

Brussels, 02. - 03.02.2013

Gerrit: Web-based Code Review

• 1 Commit ⇒ 1 Change

7

That’s the list of open changes for all projects. One change her refers to one commit that is reviewed.

Brussels, 02. - 03.02.2013

Gerrit: Web-based Code Review

• Change Details Screen

change meta data

reviews

commit message

8

The Change-Id is a very interesting thing. Due to the time constraints, I’m not able to tell the whole truth in the talk itself - so here’s the explanation:

If you want to have Patch Set 1 and Patch Set 2 to appear in the same change request in Gerrit, you need that Change-Id to stay the same for all versions of the commit (different versions created through `git commit --amend`.

Every contributor needs the commit-msg hook in his Git repo, before the commit is made. This auto-generates the Change-Id and adds it to the commit message. See http://gerrit-documentation.googlecode.com/svn/Documentation/2.5/cmd-hook-commit-msg.html

Brussels, 02. - 03.02.2013

• Commit Details

Gerrit: Web-based Code Review

add your review

changed files

open diffviews

get changespatch set history

9

Different versions of the same commit are grouped in one change request. You can compare different patch set versions. That’s nice :)

Brussels, 02. - 03.02.2013

Gerrit: Web-based Code Review

• Diff view with comments

10

Brussels, 02. - 03.02.2013

Review WorkflowGraphics by Chris Aniszczyk

Thanks!

git push origin HEAD:refs/for/master

11

enough votes collected

git commit --amend

the “enough votes collected” state can be defined by Prolog Submit rules. One can’t submit a change, if there aren’t enough positive reviews.

Brussels, 02. - 03.02.2013

Gerrit as Git Server

• Full-featured¹ Git server functionality, based on JGit

• Smart HTTP and SSH access to repos

• Gitweb integration, Gitblit integration under development

• Fine-grained access control settings

• Per-branch

• Push commits from different author/committer

• Allow merges, forced push, branch deletion

• ...

¹As JGit has only experimental garbage collection, you should run `git gc` manually from time to time

12

The Git protocol is not supported by Gerrit itself. However, using built-in replication to the same/another host running a Git daemon is pretty common and easy.

Access control settings are on a per-branch level. So one group might be allowed to push directly to branch A, but not to B

Brussels, 02. - 03.02.2013

Example Access Control Settings 13

Group Permissions via Git Permissions via Web UI

Anonymous Clone Repo Browse Changes

Registered Users Push for Review Review (Comment, +1 Vote)

Team Members Review (+2 Vote), Submit

Team Leaders Create Branches + Tags Abandon Changes, Manage Team

intorepo

right

s in

herit

ed to

p to

bot

tom

Team Members Push

No reviews required? (use as normal Git server)

Usually, you don’t want anybody to bypass review. In doubt, one can self-approve his own change, if it’s trivial.

It’s perfectly fine to use Gerrit also as a “normal” Git server by allowing committers to push directly to master.

Brussels, 02. - 03.02.2013

More Goodies

• Mylyn connector for eclipse

• Authentication

• OpenID, LDAP, Apache External Auth

• Patches for custom auth pending

• Prolog submit rules

• Stabilized Development

• Lead by Google staff

• ~10 committers from different companies(Google, SAP, Sony Mobile, Codeaurora, ..)

14

Using an Apache as proxy in front of Gerrit (pretty common) and by using Apache’s External Auth, you can basically authenticate against everything. You can find our config here:https://gist.github.com/4531841

Prolog rules allow you to define conditions, which lead to a change getting approved (= to be submittable). You can e.g. require votes by three persons, while none of them is the author of the patch. AFAIK also possible on a per-branch level. Haven’t looked into that too deep, but see here: https://gerrit-review.googlesource.com/Documentation/prolog-cookbook.html

Brussels, 02. - 03.02.2013

Gerrit Users

• Open Source projects, public

• Commercial, non-public

• SAP, Sony Mobile, Intel, Qualcomm, eBay, Garmin, QT, Ericsson, nVidia, Red Hat, LibreOffice, ...

Source and more users: http://en.wikipedia.org/wiki/Gerrit_(software)

android-review.googlesource.comgerrit-review.googlesource.com

review.openstack.org gerrit.wikimedia.org

git.eclipse.org/r/

15

gerrit.libreoffice.org

What might look a bit scary at the first moment (compared to Github) is actually pretty nice - and used by several other projects, too!

Brussels, 02. - 03.02.2013

Gerrit in the TYPO3 project

plus my personal opinion

16

Brussels, 02. - 03.02.2013

What’s TYPO3?

• TYPO3 CMS

• Started: 1997, first release: 1999

• More than 5M downloads

• PHP-based, GPLv2

• New products

• TYPO3 Flow: PHP framework

• “TYPO3 Flow and the Joy of Development” by Robert Lemke from yesterday

• TYPO3 Neos

• New CMS based on TYPO3 Flow - alpha state

17

Brussels, 02. - 03.02.2013

Development of TYPO3

• Development steered through Core Teams (10-25 people)

• Mailing list used for Reviews in 2005-2011

• Patches and +1/-1 sent via mail

• Big changes were a PITA

• Reviews are not new to TYPO3

• Replaced by Git and Gerrit

18

Brussels, 02. - 03.02.2013

Gerrit at TYPO3 (review.typo3.org)

• TYPO3 Flow in 08/2010

• TYPO3 CMS in 03/2011

• 10.669 commits with SVN

• 4300+ commits with Git

19

Commits counter over all branches (in master branch only there are 2600+ with git and 7022 with svn)

Brussels, 02. - 03.02.2013

More Statistics

• 190 projects (official Git support still not announced)

• 17.7k changes, 31.6k patch sets, 14.4k comments

• 400 people commenting

• 291 unique uploaders(5 guys with > 1000 patch sets, 55 with > 100 patch sets)

• biggest project: 5100+ changes (TYPO3 CMS Core)

• patch sets per change

• 155 changes with 10+ patch sets

• biggest with 35 patch sets

20

Stats taken 27.01.2013

Brussels, 02. - 03.02.2013

Implemented Workflow

• New patch set uploaded

• Humans are notified via Email

• Jenkins is triggered and executes code sniffs

• Issue tracker (Redmine) is updated

• Change merged

• TravisCI executes unit tests

• Issue closed

• packagist.org notified for composer packages

• Documentation rendering triggered

• Under development

• TravisCI for every patch set

21

Hooks available!

We are using the populer “Gerrit Trigger” plugin: https://wiki.jenkins-ci.org/display/JENKINS/Gerrit+Trigger

Redmine and packagist.org are updated via Gerrit hooks

TravisCI (http://travis-ci.org) relies on Github. So we’re replicating to Github and let Travis grab it from there.To run TravisCI during review, we’re currently testing the following process:- Fork TYPO3v4-Core repo, apply changes, create a pull request- Travis will pick this one, execute tests and give feedback into the pull request- Read Travis’ vote from Github and add it as voting to GerritContact me or Andy Grunwald <andygrunwald@googlemail.com> for details

Brussels, 02. - 03.02.2013

Personal Comment

• Brings quality and transparency into your (open source) project

• Easy to improve other’s work - strive for perfect code!

• Mature and very stable software, very active maintainers

• Well documented

• Integration into infrastructure costs severe amount of work

• Beginner’s barrier exists. Provide instructions! (see wiki.typo3.org/Git)

• Some people say it’s impersonal (but avatar support upcoming)

22

Photo by stylesr1http://www.sxc.hu/photo/605324

Brussels, 02. - 03.02.2013

• Happy to receiveyour questions!

• @StGebert on Twitter

• steffen.gebert@typo3.org

Foto “Question mark”: Yello-Doghttp://www.sxc.hu/photo/1279316

• Slides availablehttp://slideshare.net/stephenking/

23

inspiring people to share

inspiring people to share

Brussels, 02. - 03.02.2013

Hot Links

• Gerrit project web site:https://code.google.com/p/gerrit/

• Gerrit Documentationhttp://gerrit-documentation.googlecode.com/svn/Documentation/

• Gerrit User Summit 2012 - Slideshttps://sites.google.com/site/gerritsummit2012/program

• Gerrit integration for Eclise - Mylyn Reviews Gerrit Connectorhttp://www.eclipse.org/reviews/gerrit/

25