Tutorial

Creating Custom Bug Listing Reports with Arsenal 2

Arsenal is a toolkit for crafting reports listing bugs that are sorted, filtered, and organized by various criteria.

In Arsenal 1, creating these reports usually required some level of proficiency with launchpadlib itself to manually craft the search. Arsenal 2 brings a new abstraction layer, called a "search config", which lets you set up your query, criteria, and filters in a simple INI-file style format.

This tutorial explains how to create and use search configs and provides a number of examples you can use as a starting point for your own reports.

Setting up Arsenal

First thing's first, you'll need a working Arsenal installation. This isn't hard, but we won't cover it here. See the installation documentation and come back when you're ready to go.

All Bugs in a Ubuntu Source Package

The most simple search just includes everything in a given package:

   1  # example.lpltk.search
   2  source.packages = python-launchpadlib-toolkit

The 'source' parameter is required in every search config. It defines where Arsenal retrieves the data from. There are several different types of source's, which we'll show in the coming examples.

Save the above snippet to the file 'example.lpltk.search', and then run it like this:

 $ collect-bugs example.lpltk.search

This will generate your JSON data file to your /tmp dir.

Bugs with a Tag

Launchpad's tagging functionality is very flexible and quite widely used, so a typical basic report would be to simply gather all bugs with a specific tag or set of tags:

   1  # example.firefox-sru-verification-todo.search
   2  source.packages = firefox, thunderbird
   3  require.tags = verification-needed, precise
   4  require.status = In Progress, Fix Committed

The 'require' parameter defines criteria to be used in the launchpadlib search_tasks() call. Unlike the source parameter, multiple require parameters can be given. Indeed, the more require's you use the better because it directly helps reduce the number of items that launchpad returns, thus making your script run faster and present less of a load on the launchpad service.

You can only use each specific require parameter one time, however most of them accept a list of arguments such as shown above. In most cases these are "OR'd" together, so that a bug task needs to match only one of the possible values. Tags are different though; by default these are "AND'd" together so a bug task must have all the listed tags.

Bugs in a Team's Packages

Within the Ubuntu distro different teams manage different sets of packages, although Launchpad doesn't provide the concept of "team owners" for distro packages. So, it's easy to look at bugs filed against each package individually, but how do you look at all bugs in all the packages your team cares about?

We do this by setting up a Team in Launchpad and then "subscribing" the team to each of the packages it maintains.

Then, in Arsenal, we use the team (or set of teams) as our source, to build a query for, say, all quantal "packaging" bug reports:

   1  # example.desktop-packaging.search
   2  source.teams = ubuntu-x-swat, ubuntu-desktop
   3  require.tags = packaging, quantal
   4  quick = True

Note the 'quick' flag at the end. This tells Arsenal to skip collecting certain data items that tend to slow down queries. That data is often not needed, so setting 'quick = True' is a good way to optimize frequently run scripts or scripts that are collecting a lot of results.

Bugs Needing Action

   1  # example.vlc-needs-action.search
   2  TODO

Bugs with Patches

   1  # example.rhythmbox-patches.search
   2  TODO

Bugs Fixed Upstream

When a bug that has been sent upstream receives a fix, the fix often can be a good candidate for backporting into the stable release. The following shows how to set up a report listing bugs that have upstream fixes in a foreign bug tracker:

   1  # example.linux-fixed-upstream.search
   2  TODO

And here's a similar example, for when the upstream uses Launchpad to track their bugs:

   1  # example.inkscape-fixed-upstream.search
   2  TODO

Bugs Assigned to Specific People

The following does a search for bugs assigned to any one of a group of people:

   1  # example.gfx-assignments.search
   2  source.packages = inkscape, gimp
   3  require.assignee = andy, bart, charlie, ubuntu-bugnauts

The Launchpad API only searches against one assignee at a time, so to gather all the required data in this case will require three separate launchpad calls, with the data merged together as it's gathered.

Let's say other people are interested in being listed in this chart, but manually updating the names is tedious and error-prone. Instead, you set up a team in Launchpad, 'ubuntu-gearheads' and add andy, bart, and charlie as direct members, and ubuntu-bugnauts as a sub-team. You can now tell Arsenal to gather bugs assigned to all members of this team:

   1  source.packages = inkscape, gimp
   2  require.assignee = ubuntu-gearheads.*

This only includes direct team membership. So this will include bugs assigned to ubuntu-bugnauts, but not to *members* of the team. To include all team members recursively down, just do this:

   1  source.packages = inkscape, gimp
   2  require.assignee = ubuntu-gearheads.*.*

Be careful though; if someone adds a large team somewhere in your team membership hierarchy this could result in a huge query.

Bugs on Other Distros

By default Arsenal assumes bugs are about the 'ubuntu' distribution, however this is trivial to change:

   1  distribution = debian
   2  source.packages = xkeyboard-config

All Assigned Bugs in a Distro

For package sources, if a wildcard is specified it performs the search against the whole distro rather than specific packages:

 distribution = xubuntu
 source.packages = *
 require.assignee = xubuntu-dev.*.*

Note that the source.package value must be '*'; general wildcarding (such as 'xfce-*') isn't implemented.

Arsenal/2/Tutorial (last edited 2012-07-13 01:51:52 by static-50-53-79-63)