I’m pleased to announce the availability of a new release of gerrymander, version 1.5. Gerrymander provides a python command line tool and APIs for querying information from the gerrit review system, as used in OpenStack and many other projects. You can get it from pypi
# pip install gerrymander
Or straight from GitHub
# git clone git://github.com/berrange/gerrymander.git
If you’re the impatient type, then go to the README file which provides a quick start guide to using the tool.
This release contains a mixture of bug fixes and new features
- Honour the ‘files’ parameter in the ‘todo-noones’ command
- Only match filenames against current patchset
- Handle pagination with gerrit >= 2.9
- Avoid looping forever if sort key is missing in results
- Don’t call encode() on integer types
- Auto-detect gerrit server from git remote
- Don’t include your own changes in todo lists
- Fix type casting of cache lifetime values in config file
- Optionally show hierarchical relationship between changes via new ‘–deps’ option
Thanks to everyone who contributed this release, whether by reporting bugs, requesting features or submitting patches.
I’m pleased to announce the availability of a new release of gerrymander, version 1.4. Gerrymander provides a python command line tool and APIs for querying information from the gerrit review system, as used in OpenStack and many other projects. You can get it from pypi
# pip install gerrymander
Or straight from GitHub
# git clone git://github.com/berrange/gerrymander.git
If you’re the impatient type, then go to the README file which provides a quick start guide to using the tool.
This release contains a mixture of bug fixes and new features
- Add command for reporting potentially approvable patches
- Add command for reporting potentially expirable patches
- Allow todo list commands to be filtered on filename
- Remove hardcoded #!/usr/bin/python3 lines
- Fix traceback on casting unicode strings
- Allow filtering reports based on topic
- Fix typo in keyfile setting in example config
Thanks to everyone who contributed patches that went into this new release
I’m pleased to announce the availability of a new release of gerrymander, version 1.3. Gerrymander provides a python command line tool and APIs for querying information from the gerrit review system, as used in OpenStack and many other projects. You can get it from pypi
# pip install gerrymander
Or straight from GitHub
# git clone git://github.com/berrange/gerrymander.git
If you’re the impatient type, then go to the README file which provides a quick start guide to using the tool.
This release contains a mixture of bug fixes and two new features. When displaying a list of changes, one of the fields that can be shown per-change is the approvals. This is rendered as a list of all the -2/-1/+1/+2 votes made against the current patch set. The text is also coloured to make it easier to tell at a glance what the overall state of the change is. There are two problems with this, first when there were a lot of votes on a change the list gets rather too wide. The bigger problem though has been the high level of false failures in the OpenStack CI testing system. This results in many patches receiving -1’s from testing, which caused gerrymander to colour them in red:
+-------------------------------------+-------------------------------------------------------+----------+-----------------------+
| URL | Subject | Created | Approvals |
+-------------------------------------+-------------------------------------------------------+----------+-----------------------+
| https://review.openstack.org/68942 | Power off commands should give guests a chance to ... | 186 days | w= v=1,1,1,1 c=-2,-1 |
| https://review.openstack.org/77027 | Support image property for config drive | 152 days | w= v=1,-1,-1,-1 c=-1 |
| https://review.openstack.org/82409 | Fixes a Hyper-V list_instances localization issue | 128 days | w= v=1,-1 c=-1 |
| https://review.openstack.org/88067 | Allow deleting instances while uuid lock is held | 104 days | w= v=1,1,1,1 c=2 |
| https://review.openstack.org/108013 | Fixes Hyper-V agent force_hyperv_utils_v1 flag iss... | 12 days | w= v=1,1,1,-1 c=1,1,1 |
My workflow is to focus on things which do not have negative feedback and so I found this was discouraging me from reviewing stuff that was only marked negative due to bogus CI failures. So in this new release, the display is now using separate columns to report test votes, code review votes and workflow votes, each column being separately coloured. Also, instead of showing each individual vote, we only show the so called “casting vote” – ie the one that’s most important, (order is -2, +2, -1, +1)
+-------------------------------------+-------------------------------------------------------+----------+-------+---------+----------+
| URL | Subject | Created | Tests | Reviews | Workflow |
+-------------------------------------+-------------------------------------------------------+----------+-------+---------+----------+
| https://review.openstack.org/68942 | Power off commands should give guests a chance to ... | 186 days | 1 | -2 | |
| https://review.openstack.org/77027 | Support image property for config drive | 152 days | -1 | -1 | |
| https://review.openstack.org/82409 | Fixes a Hyper-V list_instances localization issue | 128 days | -1 | -1 | |
| https://review.openstack.org/88067 | Allow deleting instances while uuid lock is held | 104 days | 1 | 2 | |
| https://review.openstack.org/108013 | Fixes Hyper-V agent force_hyperv_utils_v1 flag iss... | 12 days | -1 | 1 | |
The second new feature is the ‘patchreviewrates’ command which is reports on the review comment activity of people over time. We already have ‘patchreviewstats’ command which gives information about review activity over a fixed window, but this doesn’t let us see long term trends. With the new command we’re reporting on the daily number of review comments per person, averaging over a week, and reported for the last 52 weeks. This lets us see how review activity from contributors goes up and down over the course of a year (or 2 dev cycles). I used this to produced a report which I then imported to LibreOffice to create a graph showing the nova-core team activity over the past two cycles (click image to enlarge)
Nova core team review rates
In summary the changes in version 1.2 of gerrymander are
- Exclude own changes in the todo lists
- Add CSV as an output format for some reports
- Add patchreviewrate report for seeing historica approvals per day
- Replace ‘Approvals’ column with ‘Test’, ‘Review’ and ‘Workflow’ columns in change reports
- Allow todo lists to be filtered per branch
- Reorder sorting of votes to prioritize +2/-2s over +1/-1s
- Avoid exception from unexpected approval vote types
- Avoid creating empty cache file when Ctrl-C’ing ssh client
- Run ssh in batch mode to avoid hang when host key is unknown
Thanks to everyone who contributed patches that went into this new release
I’m pleased to announce the availability of a new release of gerrymander, version 1.2. Gerrymander provides a python command line tool and APIs for querying information from the gerrit review system, as used in OpenStack and many other projects. You can get it from pypi
# pip install gerrymander
Or straight from GitHub
# git clone git://github.com/berrange/gerrymander.git
If you’re the impatient type, then go to the README file which provides a quick start guide to using the tool.
The changes in version 1.2 are
- Don’t drop ‘Restored’ comments in ‘comments’ command
- Change ‘assertEquals’ to ‘assertEqual’
- Print list of options for ‘changes’ command in help message
- Send all output via a pager (eg less or whatever $PAGER says) Can disable via setting GERRYMANDER_PAGER=cat env var.
- Fix ordering of comments when > 10 patch sets are present
- Handle remaining event types
- Stop subprocesses getting signals intended for main process
- Improve colourization of review votes
Thanks to everyone who contributed patches that went into this new release
This blog post is to announce the first release of a new project, gerrymander, which I’ve mentioned on IRC in passing a few times. The 32,000 ft summary is that it provides a set of python (2 & 3 compatible) APIs and command line tool for extracting and presenting information from gerrit. You can get it from pypi
# pip install gerrymander
Or straight from GitHub
# git clone git://github.com/berrange/gerrymander.git
If you’re the impatient type, then go to the README file which provides a quick start guide to using the tool.
For details on why/how I built gerrymander, read onwards….
Background motivation
The OpenStack project uses Gerrit for review of pretty much all contributions to the project. Not wishing to get into a discussion of the merits of using a Gerrit based workflow, I’ll just say that with large volume of changes going through some sub-projects, such as Nova, the Gerrit web interface really starts to show its limitations. As a result a number of OpenStack contributors have developed cli tools for extracting information from Gerrit and presenting it in more practical formats.
- gerrit_view – created by Josh Harlow, it provides a general purpose query tool and a interactive TUI for live monitoring of changes.
- reviewtodo – created by Russell Bryant, it generates reports which attempt to prioritize changes such that the most “important” ones are presented at the top of the todo list.
- reviewstats – created by Russell Bryant, it generates reports which summarize the reviewing activity of all contributors across the project, and reports which attempt to identify how efficiently reviews are being handled.
I’ve previously contributed to the gerrit_view project and in the second half of the IceHouse dev cycle, I turned off gerrit email alerts and stopped using the gerrit web UI index pages for identifying changes needing review. Instead I exclusively use the qgerrit command line tool to identify changes that affect the libvirt driver which need attention from myself. This had a significant positive impact on my productivity when using gerrit, so I started looking at other gerrit client tools and thinking about what further reports or information I might wish to get from gerrit. It became apparent that the tools people are writing have significant overlap / duplication of code for dealing with basic interaction with gerrit. There are features in some tools (eg caching of gerrit queries in reviewstats) which would be useful to the other tools, but since these are all designed as singe-purpose standalone tools there’s not really much scope for sharing functionality.
Introducing the “gerrymander” project
Clearly what was needed was a new “standard” for building gerrit command line tools, so enter “gerrymander“. The gerrymander project is not simply another command line tool, rather it is intended to provide a collection of python modules / APIs to facilitate the creation of arbitrary gerrit command line reports/tools. With that goal in mind the gerrymander package provides a set of modules, for both Python 2 and Python 3:
- gerrymander.client – module providing a class for connecting to the gerrit server over SSH, running the ‘gerrit’ tool and passing the results to a callback for processing. As well as the standard “live” client, there is a caching client which stores the results from ‘gerrit’ in local files. This means that expensive queries (eg querying the entire history of all changes ever) won’t inflict repeated denial of service attacks on the server.
- gerrymander.model – module providing a set of classes that represent the JSON schemas returned by the ‘gerrit’ tool as Python objects. This means you’re not simply blindly accessing untyped dictionary fields. Many of the classes have helper APIs against them to allow their information to be accessed in interesting ways.
- gerrymander.format – module providing a few helper APIs for formatting data to present to the user. For example, a way to produce coloured text for ANSI capable terminals, or to format time deltas / dates in more user friendly ways (ie “4 days ago” instead of “May 5, 2014”).
- gerrymander.operation – module providing a class for each operation supported by the ‘gerrit’ tool. This provides a slightly higher level way to utilize to the gerrymander.client module classes. This takes care of obscure oddities such as the need to re-execute ‘gerrit query’ multiple times, since it refuses to return more than 500 results at a time.
- gerrymander.reports – module providing a set of classes for extracting interesting information from gerrit. Each report class will execute one of more operations against gerrit, post-process the data from the query, and then return an object with the structured results. This is where all the really interesting functionality lives.
- gerrymander.commands – module providing the command line interface to the reports. It takes the report output and formats it as text, xml or json. A configuration file is used to customize default behaviour, such as which fields are visible, defining command lines, project names, usernames of bots, etc.
The actual “gerrymander” command line tool is designed as a multi-call binary – ie it has a number to sub-commands you can execute, each with their own set of options. I won’t repeat what’s already covered in the README file in this blog post, rather just see the help message for the list of reports/commands I’ve written. So far I’ve targeted the functionality provided by the 3 pre-existing projects I mentioned above:
$ gerrymander --help
usage: gerrymander [-h] [-c CONFIG] [-d] [-q]
{watch,todo-noones,todo-anyones,todo-mine,todo-others,patchreviewstats,openreviewstats,changes,comments,changes-nova-specs}
...
Gerrymander client
positional arguments:
{watch,todo-noones,todo-anyones,todo-mine,todo-others,patchreviewstats,openreviewstats,changes,comments,changes-nova-specs}
watch Watch incoming changes
todo-noones List of changes no one has looked at yet
todo-anyones List of changes anyone has looked at
todo-mine List of changes I've looked at before
todo-others List of changes I've not looked at before
patchreviewstats Statistics on patch review approvals
openreviewstats Statistics on open patch reviews
changes Query project changes
comments Display comments on a change
changes-nova-specs Changes in Nova SPECS
optional arguments:
-h, --help show this help message and exit
-c CONFIG, --config CONFIG
Override config file (default
/home/berrange/.gerrymander)
-d, --debug Display debugging information
-q, --quiet Supress display of warnings
As one example, taking the simplest / most generic ‘changes’ command, lets see all changes that I’ve written but abandoned
$ gerrymander changes --owner berrange --status abandoned
Changes
-------
+-----------+------------------------------------+----------+-----------------------------------+----------+----------+------------------+
| Status | URL | Owner | Subject | Created | Updated | Approvals |
+-----------+------------------------------------+----------+-----------------------------------+----------+----------+------------------+
| ABANDONED | https://review.openstack.org/8528 | berrange | Allow CPU model to be specifie... | 694 days | 688 days | v=-1,1 c=-1 |
| ABANDONED | https://review.openstack.org/9356 | berrange | Fix use of uninitialized varia... | 673 days | 672 days | v=-1 c=1 |
| ABANDONED | https://review.openstack.org/10871 | berrange | Revert "Handle InstanceNotFoun... | 641 days | 641 days | v=-1 |
| ABANDONED | https://review.openstack.org/18869 | berrange | Merge LibvirtOpenVswitchVirtua... | 490 days | 486 days | |
| ABANDONED | https://review.openstack.org/19127 | berrange | Merge all VIF classes into one... | 486 days | 463 days | v=1,1 c=1 |
| ABANDONED | https://review.openstack.org/19214 | berrange | Make it possible to set nova o... | 485 days | 483 days | v=1 c=1,-1 |
| ABANDONED | https://review.openstack.org/29784 | berrange | Make devstack work on Fedora 1... | 353 days | 336 days | v=1 c=-1,1,-1,-1 |
| ABANDONED | https://review.openstack.org/58494 | berrange | Increase min required libvirt ... | 164 days | 79 days | v=-1 c=-1 |
| ABANDONED | https://review.openstack.org/76902 | berrange | Fix quoting of username in pol... | 70 days | 63 days | v=1 c=-1 |
+-----------+------------------------------------+----------+-----------------------------------+----------+----------+------------------+
Some things to note about that are unique in comparison to other gerrit client tools I’ve mentioned above that can do the same kind of query
- The gerrit query is cached for 5 minutes, so if you re-run to change the display options (eg which fields are shown) it won’t hit the gerrit server again, unless you change the actual args to the query.
- The default output mode is formatted text, but you can ask for the data in XML or JSON documents, allowing easier parsing by further downstream tools
- The configuration file lets you set defaults for all of the command line parameters. So you can hide fields you don’t care about, or make fields wider, and more
- The configuration file lets you define command aliases. So if you have a number of different queries you run, you can define new commands (eg ‘my-abandoned-changes’) which record all the query parameters for the ‘changes’ command. This avoids the need to create shell wrapper scripts around the gerrymander command for common queries
- The command and/or report are accessible via the Python API, so if you want direct access to the raw data you can use the API instead of parsing the text/xml/json outputs.
- Optional colourization of fields (eg +1’s / +2’s in green, -1’s / -2’s in red)
If any of this sounds interesting to you, pip install the package and try it out. If you want to contribute patches for more interesting reports, then the code is all up on github at the URL mentioned earlier.
One final important point is that this tool is written such that it has zero knowledge about OpenStack. It is intended to be useful to any project which is using Gerrit for their code review. As such all the projects specific knowledge, such as list of project names, team members, bot accounts, is isolated in the configuration file. So one thing I need to do to ease first time users is to upload a sample configuration file for OpenStack that includes all the different projects / teams / bots OpenStack has.
EDIT: Use this config file with OpenStack
