~launchpad-pqm/launchpad/devel

= ExternalBugTracker: Roundup =

This covers the implementation of the ExternalBugTracker class for Roundup

bugwatches.

== Basics ==

The ExternalBugTracker descendant class which implements methods for updating

bug watches on Roundup bug trackers is externalbugtracker.Roundup, which

implements IExternalBugTracker.

    >>> from lp.bugs.externalbugtracker import Roundup

    >>> from lp.bugs.interfaces.bugtracker import BugTrackerType

    >>> from lp.bugs.interfaces.externalbugtracker import IExternalBugTracker

    >>> from lp.bugs.tests.externalbugtracker import (

    ...     new_bugtracker)

    >>> from canonical.launchpad.webapp.testing import verifyObject

    >>> verifyObject(

    ...     IExternalBugTracker,

    ...     Roundup('http://example.com'))

    True

== Status Conversion ==

The basic Roundup bug statuses (i.e. those available by default in new

Roundup instances) map to Launchpad bug statuses.

Roundup.convertRemoteStatus() handles the conversion.

    >>> roundup = Roundup('http://example.com/')

    >>> roundup.convertRemoteStatus('1').title

    'New'

    >>> roundup.convertRemoteStatus('2').title

    'Confirmed'

    >>> roundup.convertRemoteStatus('3').title

    'Incomplete'

    >>> roundup.convertRemoteStatus('4').title

    'Incomplete'

    >>> roundup.convertRemoteStatus('5').title

    'In Progress'

    >>> roundup.convertRemoteStatus('6').title

    'In Progress'

    >>> roundup.convertRemoteStatus('7').title

    'Fix Committed'

    >>> roundup.convertRemoteStatus('8').title

    'Fix Released'

Some Roundup trackers are set up to use multiple fields (columns in

Roundup terminology) to represent bug statuses. We store multiple

values by joining them with colons. The Roundup class knows how many

fields are expected for a particular remote host (for those that we

support), and will generate an error when we have more or less field

values compared to the expected number of fields.

    >>> roundup.convertRemoteStatus('1:2')

    Traceback (most recent call last):

      ...

    UnknownRemoteStatusError: 1 field(s) expected, got 2: 1:2

If the status isn't something that our Roundup ExternalBugTracker can

understand an UnknownRemoteStatusError will be raised.

    >>> roundup.convertRemoteStatus('eggs').title

    Traceback (most recent call last):

      ...

    UnknownRemoteStatusError: Unrecognized value for field 1 (status): eggs

== Initialization ==

Calling initializeRemoteBugDB() on our Roundup instance and passing it a set

of remote bug IDs will fetch those bug IDs from the server and file them in a

local variable for later use.

We use a test-oriented implementation for the purposes of these tests, which

overrides ExternalBugTracker.urlopen() so that we don't have to rely on a

working network connection.

    >>> from lp.bugs.tests.externalbugtracker import (

    ...     TestRoundup, print_bugwatches)

    >>> roundup = TestRoundup(u'http://test.roundup/')

    >>> roundup.initializeRemoteBugDB([1])

    >>> sorted(roundup.bugs.keys())

    [1]

== Export Methods ==

There are two means by which we can export Roundup bug statuses: on a

bug-by-bug basis and as a batch. When the number of bugs that need updating is

less than a given bug roundupker's batch_query_threshold the bugs will be

fetched one-at-a-time:

    >>> roundup.batch_query_threshold

    10

    >>> roundup.trace_calls = True

    >>> roundup.initializeRemoteBugDB([6, 7, 8, 9, 10])

    CALLED urlopen(u'http://test.roundup/issue?...&id=6')

    CALLED urlopen(u'http://test.roundup/issue?...&id=7')

    CALLED urlopen(u'http://test.roundup/issue?...&id=8')

    CALLED urlopen(u'http://test.roundup/issue?...&id=9')

    CALLED urlopen(u'http://test.roundup/issue?...&id=10')

If there are more than batch_query_threshold bugs to update then they are

fetched as a batch:

    >>> roundup.batch_query_threshold = 4

    >>> roundup.initializeRemoteBugDB([6, 7, 8, 9, 10])

    CALLED urlopen(u'http://test.roundup/issue?...@startwith=0')

== Updating Bug Watches ==

First, we create some bug watches to test with:

    >>> from lp.bugs.interfaces.bug import IBugSet

    >>> from lp.registry.interfaces.person import IPersonSet

    >>> sample_person = getUtility(IPersonSet).getByEmail('test@canonical.com')

    >>> example_bug_tracker = new_bugtracker(BugTrackerType.ROUNDUP)

    >>> from canonical.launchpad.interfaces.launchpad import ILaunchpadCelebrities

    >>> example_bug = getUtility(IBugSet).get(10)

    >>> example_bugwatch = example_bug.addWatch(

    ...     example_bug_tracker, '1',

    ...     getUtility(ILaunchpadCelebrities).janitor)

Collect the Example.com watches:

    >>> print_bugwatches(example_bug_tracker.watches)

    Remote bug 1: None

And have a Roundup instance process them:

    >>> transaction.commit()

    >>> from canonical.testing.layers import LaunchpadZopelessLayer

    >>> from lp.bugs.scripts.checkwatches import CheckwatchesMaster

    >>> txn = LaunchpadZopelessLayer.txn

    >>> bug_watch_updater = CheckwatchesMaster(txn)

    >>> roundup = TestRoundup(example_bug_tracker.baseurl)

    >>> bug_watch_updater.updateBugWatches(

    ...     roundup, example_bug_tracker.watches)

    INFO:...:Updating 1 watches for 1 bugs on http://bugs.some.where

    >>> print_bugwatches(example_bug_tracker.watches)

    Remote bug 1: 1

We'll add some more watches now.

    >>> from lp.bugs.interfaces.bugwatch import IBugWatchSet

    >>> print_bugwatches(example_bug_tracker.watches,

    ...     roundup.convertRemoteStatus)

    Remote bug 1: New

    >>> remote_bugs = [

    ...     (2, 'Confirmed'),

    ...     (3, 'Incomplete'),

    ...     (4, 'Incomplete'),

    ...     (5, 'In Progress'),

    ...     (9, 'In Progress'),

    ...     (10, 'Fix Committed'),

    ...     (11, 'Fix Released'),

    ...     (12, 'Incomplete'),

    ...     (13, 'Incomplete'),

    ...     (14, 'In Progress')

    ... ]

    >>> bug_watch_set = getUtility(IBugWatchSet)

    >>> for remote_bug_id, remote_status in remote_bugs:

    ...     bug_watch = bug_watch_set.createBugWatch(

    ...         bug=example_bug, owner=sample_person,

    ...         bugtracker=example_bug_tracker,

    ...         remotebug=str(remote_bug_id))

    >>> roundup.trace_calls = True

    >>> bug_watch_updater.updateBugWatches(

    ...     roundup, example_bug_tracker.watches)

    INFO:...:Updating 11 watches for 11 bugs on http://bugs.some.where

    CALLED urlopen(u'http://.../issue?...@startwith=0')

    >>> print_bugwatches(example_bug_tracker.watches,

    ...     roundup.convertRemoteStatus)

    Remote bug 1: New

    Remote bug 2: Confirmed

    Remote bug 3: Incomplete

    Remote bug 4: Incomplete

    Remote bug 5: In Progress

    Remote bug 9: In Progress

    Remote bug 10: Fix Committed

    Remote bug 11: Fix Released

    Remote bug 12: Incomplete

    Remote bug 13: Incomplete

    Remote bug 14: In Progress