Using Gerrit Code Review in an Open Source Project
1. Brussels, 02. - 03.02.2013
1
Using Gerrit Code Review
in an
Open Source Project
License: CC BY-SA 3.0
(pictures of other authors excluded)
2. Brussels, 02. - 03.02.2013
Contents of this talk 2
• 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
3. Brussels, 02. - 03.02.2013
Steffen Gebert 3
• 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.org
Twitter: @StGebert
I’m not affiliated with Gerrit or Google. Just a happy user (and contributor of 4 tiny patches)
4. Brussels, 02. - 03.02.2013
Questions! 4
• Happy to answer
your questions!
• Come down here
after the talk!
comments included!
• Slides available
Foto “Question mark”: Yello-Dog
http://www.sxc.hu/photo/1279316
http://slideshare.net/stephenking/
nice that you found the slides - have fun ☺
5. Brussels, 02. - 03.02.2013
Motivation for Code Reviews 5
• 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
Example Policy:
• Learn from others
“Every ch
ange has
be review to
ed by at
least two
other
persons”
Based on a photo by CMSeter
http://www.sxc.hu/photo/1062451
With Gerrit you can actually enforce these policies, also for team members.
7. Brussels, 02. - 03.02.2013
Gerrit: Web-based Code Review 7
• 1 Commit 1 Change
That’s the list of open changes for all projects. One change her refers to one commit that is
reviewed.
8. Brussels, 02. - 03.02.2013
Gerrit: Web-based Code Review 8
• Change Details Screen
commit message
change meta data
reviews
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
9. Brussels, 02. - 03.02.2013
Gerrit: Web-based Code Review 9
• Commit Details
patch set history
get changes
open diff
views
add your review
changed files
Different versions of the same commit are grouped in one change request. You can compare
different patch set versions. That’s nice :)
11. Brussels, 02. - 03.02.2013
Review Workflow 11
Graphics by Chris Aniszczyk
Thanks!
git push origin HEAD:refs/for/master
git commit --amend
enough votes collected
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.
12. Brussels, 02. - 03.02.2013
Gerrit as Git Server 12
• 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
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
13. Brussels, 02. - 03.02.2013
Example Access Control Settings 13
Group Permissions via Git Permissions via Web UI
rights inherited top to bottom
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
into
No reviews required? (use as normal Git server) repo
Team Members Push
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.
14. Brussels, 02. - 03.02.2013
More Goodies 14
• 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, ..)
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
15. Brussels, 02. - 03.02.2013
Gerrit Users 15
• Open Source projects, public
gerrit-review.
android-review.googlesource.com googlesource.com git.eclipse.org/r/
gerrit.libreoffice.org review.openstack.org gerrit.wikimedia.org
• 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)
What might look a bit scary at the first moment (compared to Github) is actually pretty nice -
and used by several other projects, too!
16. Brussels, 02. - 03.02.2013
16
Gerrit in the TYPO3 project
plus m
perso y
nal
opinio
n
17. Brussels, 02. - 03.02.2013
What’s TYPO3? 17
• 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
18. Brussels, 02. - 03.02.2013
Development of TYPO3 18
• 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
19. Brussels, 02. - 03.02.2013
Gerrit at TYPO3 (review.typo3.org) 19
• TYPO3 Flow in 08/2010
• TYPO3 CMS in 03/2011
• 10.669 commits with SVN
• 4300+ commits with Git
Commits counter over all branches (in master branch only there are 2600+ with git and 7022
with svn)
20. Brussels, 02. - 03.02.2013
More Statistics 20
• 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
Stats taken 27.01.2013
21. Brussels, 02. - 03.02.2013
Implemented Workflow 21
• 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
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 Gerrit
Contact me or Andy Grunwald <andygrunwald@googlemail.com> for details
22. Brussels, 02. - 03.02.2013
Personal Comment 22
• 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)
Photo by stylesr1
http://www.sxc.hu/photo/605324
23. Brussels, 02. - 03.02.2013
23
• Happy to receive
your questions!
• @StGebert on Twitter
• steffen.gebert@typo3.org
• Slides available
Foto “Question mark”: Yello-Dog
http://www.sxc.hu/photo/1279316
http://slideshare.net/stephenking/