[openstack-dev] Using gerrymander, a client API and command line tool for gerrit

Daniel P. Berrange berrange at redhat.com
Thu Aug 14 16:54:27 UTC 2014

Over the past couple of months I've worked on creating a python library
and command line tool for dealing with gerrit. I've blogged about this
a number of times on http://planet.openstack.org, but I figure there are
quite a few people who won't be reading the blogs there or easily miss
some posts hence this mail to alert people to its existance.

Gerrymander was born out of my frustration with the inefficiency of
handling reviews through the gerrit web UI. In particular (until
today - yay !) the review comments were splattered with noise from
CI bots, and it was hard to generate some kinds of reports for lists
of reviews you might want. The gerrit upgrade has improved the latter
to with better query language support, but it is still somewhat limited
in the way it can present the results and I prefer the CLI reports over
web UI anyway.

You might be familiar with tools like gerrit_view, reviewtodo and
reviewstats written by Josh Harlow and / or Russell Bryant in the
past. As a starting point, gerrymander aimed to offer all the
functionality present in those tools. More importantly though was
the idea to write it as a set of a python classes rather than just
put everything in a command line tool. This makes it easy for people
to customize & extend its functionality to pull our new interesting
types of data.

Personally, using gerrymander to query gerrit for reviews and being
able to quickly get a list of comments filtered for bots has had a
big positive impact on my efficiency as a core reviewer. I've been
able to review more code in less time and focus my attention better.
So if you are the kind of person who is more comfortable with having
command line tools instead of pointy-clicky web UIs, I'd encourage
you to try it out for yourself. Hopefully it will be of as much use
to other reviewers as it has been for me.

You can get it from pypi  (pip install gerrymander) and for a quick
start guide, check out the README file


Or my blog posts


It is intended to work with any Gerrit instance, not just openstack,
so you'll need a config file that tailors it for openstack world,
like our team membership, bot accounts, etc. I've got a demo config
file here that should point you in the right direction at least:


Feel free to update that wiki to add more project teams I've not
covered already, since there's many openstack projects I've not
familiar enough with.

NB, I've tested it to work on Linux systems. It would probably work
on OS-X since that resembles UNIX well enough, but Windows people
might be out of luck since it relies on forking stuff like ssh
and less with pipes connecting them up.

In terms of how I personally use it (assuming the above config file)...

At least once a day I look at all open changes in Nova which touch any
libvirt source files

  $ gerrymander -g nova --branch master libvirt

and will go through and review anything that I've not seen before.

In addition I'll process any open changes where I have commented on a
previous version of a patch, but not commented in the current version
which is a report generated by a special command:

  $ gerrymander -g nova todo-mine

If I have more time I'll look at any patches which have been submitted
where *no  one* has done any review, touching anything in nova source

  $ gerrymander -g nova todo-noones

or any patches where I've not reviewed the current version

  $ gerrymander -g nova todo-others

That's pretty much all I need on a day-to-day basis to identify stuff
needing my review attention. For actual review I'll use the gerrit
web UI, or git fetch the patch locally depending on complexity of the
change in question. Also if I want to see comments fully expanded,
without bots, for a specific change number 104264 I would do

  $ gerrymander comments 104264

One day I'd love to be able to write some reports which pull priority
data on blueprints from nova-specs or launchpad, and correlate with 
reviews so important changes needing attention can be highlighted...

|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org       -o-       http://live.gnome.org/gtk-vnc :|

More information about the OpenStack-dev mailing list