~launchpad-pqm/launchpad/devel

= Bug Nomination =

A bug supervisor can nominate a bug to be fixed in a specific
distribution or product series. Nominations are created by
calling IBug.addNomination.

    >>> from zope.component import getUtility
    >>> from zope.interface.verify import verifyClass
    >>> from zope.security.proxy import removeSecurityProxy
    >>> from canonical.launchpad.ftests import login_person
    >>> from lp.bugs.interfaces.bug import IBugSet
    >>> from lp.bugs.interfaces.bugnomination import IBugNomination
    >>> from lp.bugs.model.bugnomination import BugNomination
    >>> from lp.registry.interfaces.distribution import IDistributionSet
    >>> from lp.registry.interfaces.person import IPersonSet
    >>> from lp.registry.interfaces.product import IProductSet
    >>> from lp.testing.sampledata import (ADMIN_EMAIL)
    >>> login(ADMIN_EMAIL)
    >>> nominator = factory.makePerson(name='nominator')
    >>> ubuntu = getUtility(IDistributionSet).getByName("ubuntu")
    >>> ubuntu = removeSecurityProxy(ubuntu)
    >>> ubuntu.bug_supervisor = nominator
    >>> firefox = getUtility(IProductSet).getByName("firefox")
    >>> firefox = removeSecurityProxy(firefox)
    >>> firefox.bug_supervisor = nominator
    >>> logout()

    >>> login_person(nominator)

The BugNomination class implements IBugNomination.

    >>> verifyClass(IBugNomination, BugNomination)
    True

    >>> bugset = getUtility(IBugSet)
    >>> bug_one = bugset.get(1)

    >>> ubuntu_grumpy = ubuntu.getSeries("grumpy")
    >>> personset = getUtility(IPersonSet)
    >>> nominator = personset.getByName("nominator")

    >>> grumpy_nomination = bug_one.addNomination(
    ...     target=ubuntu_grumpy, owner=nominator)

The nomination records the distro series or series for which the bug
was nominated and the user that submitted the nomination (the "owner").

    >>> print grumpy_nomination.owner.name
    nominator

    >>> print grumpy_nomination.distroseries.fullseriesname
    Ubuntu Grumpy

Let's create another nomination, this time on a product series.

    >>> from lp.registry.interfaces.product import IProductSet

    >>> firefox = getUtility(IProductSet).getByName("firefox")

    >>> firefox_trunk = firefox.getSeries("trunk")

    >>> nominator = personset.getByName("nominator")

    >>> firefox_ms_nomination = bug_one.addNomination(
    ...     target=firefox_trunk, owner=nominator)

    >>> print firefox_ms_nomination.owner.name
    nominator

    >>> print firefox_ms_nomination.productseries.title
    Mozilla Firefox trunk series

The target of a nomination can also be accessed through its target
attribute.

    >>> print grumpy_nomination.target.bugtargetdisplayname
    Ubuntu Grumpy

    >>> print firefox_ms_nomination.target.bugtargetdisplayname
    Mozilla Firefox trunk

Use IBug.canBeNominatedFor to see if a bug can be nominated for a
particular distroseries or productseries. This will consider whether
the bug has already been nominated for that series, or even already
targeted to that series without a nomination, which can happen for bugs
that were reported prior to the release management/nomination
functionality existing.

    >>> ubuntu_breezy_autotest = ubuntu.getSeries("breezy-autotest")

    >>> bug_one.canBeNominatedFor(firefox_trunk)
    False

    >>> bug_one.canBeNominatedFor(ubuntu_grumpy)
    False

    >>> bug_one.canBeNominatedFor(ubuntu_breezy_autotest)
    True

Bug five is already targeted to Ubuntu Warty, so even though it has no
Warty nominations, it cannot be targeted to Warty.

    >>> bug_five = bugset.get(5)

    >>> def by_bugtargetdisplayname(bugtask):
    ...     return bugtask.target.bugtargetdisplayname.lower()

    >>> tasks = sorted(bug_five.bugtasks, key=by_bugtargetdisplayname)

    >>> for task in tasks:
    ...     print task.target.bugtargetdisplayname
    Mozilla Firefox
    Mozilla Firefox 1.0
    mozilla-firefox (Ubuntu Warty)

    >>> ubuntu_warty = ubuntu.getSeries("warty")
    >>> bug_five.canBeNominatedFor(ubuntu_warty)
    False

The getNominationFor() method returns a nomination for a specific
productseries or distroseries. If there is no nomination for the target
provided, a NotFoundError is raised.

    >>> bug_one.getNominationFor(firefox_trunk)
    <BugNomination ...>

    >>> bug_one.getNominationFor(ubuntu_grumpy)
    <BugNomination ...>

    >>> bug_one.getNominationFor(ubuntu_breezy_autotest)
    Traceback (most recent call last):
      ...
    NotFoundError: ...

IBug.getNominations() returns a list of all IBugNominations for a bug,
ordered by IBugTarget.bugtargetdisplayname.

    >>> nominations = bug_one.getNominations()

    >>> [nomination.target.bugtargetdisplayname for nomination in nominations]
    [u'Mozilla Firefox 1.0', u'Mozilla Firefox trunk',
     u'Ubuntu Grumpy', u'Ubuntu Hoary']

This method also accepts a target argument, for further filtering.

    >>> nominations = bug_one.getNominations(firefox)

    >>> [nomination.target.bugtargetdisplayname for nomination in nominations]
    [u'Mozilla Firefox 1.0', u'Mozilla Firefox trunk']

    >>> nominations = bug_one.getNominations(ubuntu)

    >>> [nomination.target.bugtargetdisplayname for nomination in nominations]
    [u'Ubuntu Grumpy', u'Ubuntu Hoary']


== Nomination Status ==

A nomination is created with an initial status of "Nominated".
Internally this state is called PROPOSED, but in the UI we display it
as "Nominated".

    >>> ubuntu_breezy_autotest_nomination = bug_one.addNomination(
    ...     target=ubuntu_breezy_autotest, owner=nominator)

    >>> print ubuntu_breezy_autotest_nomination.status.title
    Nominated
    >>> ubuntu_breezy_autotest_nomination.isProposed()
    True
    >>> ubuntu_breezy_autotest_nomination.isApproved()
    False
    >>> ubuntu_breezy_autotest_nomination.isDeclined()
    False

Nomination status changes have an associated workflow. For this reason,
setting status directly is not possible.

    >>> from lp.bugs.interfaces.bugnomination import BugNominationStatus

    >>> nomination.status = BugNominationStatus.APPROVED
    Traceback (most recent call last):
      ...
    ForbiddenAttribute: ...

The status of a nomination is changed by calling either the approve() or
decline() method. Only users with launchpad.Driver permission on the
nomination can approve or decline it.

    >>> from canonical.launchpad.webapp.authorization import check_permission
    >>> from canonical.launchpad.webapp.interfaces import ILaunchBag

    >>> current_user = getUtility(ILaunchBag).user

    >>> current_user == nominator
    True
    >>> check_permission("launchpad.Driver", firefox_ms_nomination)
    False

    >>> firefox_ms_nomination.approve(nominator)
    Traceback (most recent call last):
      ..
    Unauthorized: ...

    >>> firefox_ms_nomination.decline(nominator)
    Traceback (most recent call last):
      ..
    Unauthorized: ...

(Log in as an admin to set the driver.)

    >>> login("foo.bar@canonical.com")

    >>> no_privs = personset.getByName("no-priv")
    >>> firefox_ms_nomination.target.driver = no_privs

    >>> login("no-priv@canonical.com")


== Approving a nomination ==

When a nomination is approved, the appropriate bugtask(s) are created on
the target of the nomination and the status is set to APPROVED.

For example, there are currently no bugtasks on the firefox_trunk
productseries.

    >>> from lp.bugs.interfaces.bugtask import BugTaskSearchParams

    >>> params = BugTaskSearchParams(user=no_privs, bug=bug_one)
    >>> found_tasks = firefox_trunk.searchTasks(params)
    >>> found_tasks.count()
    0

When a nomination is approved, one task is created, targeted at
firefox_trunk.

    >>> firefox_ms_nomination.approve(no_privs)

    >>> firefox_ms_nomination.isApproved()
    True
    >>> firefox_ms_nomination.isProposed()
    False
    >>> firefox_ms_nomination.isDeclined()
    False

    >>> found_tasks.count()
    1
    >>> bugtask = found_tasks[0]
    >>> bugtask.target == firefox_trunk
    True
    >>> print bugtask.owner.name
    no-priv

When a distribution bug nomination is approved, a task is created for
each package the bug affects in that distro. For example, let's ensure
bug #1 affects more than one Ubuntu package.

    >>> from lp.bugs.interfaces.bugtask import IBugTaskSet

    >>> ubuntu_tbird = ubuntu.getSourcePackage("thunderbird")
    >>> ignore = factory.makeSourcePackagePublishingHistory(
    ...     distroseries=ubuntu.currentseries,
    ...     sourcepackagename=ubuntu_tbird.sourcepackagename)

    >>> getUtility(IBugTaskSet).createTask(
    ...     bug=bug_one, owner=no_privs,
    ...     distribution=ubuntu,
    ...     sourcepackagename=ubuntu_tbird.sourcepackagename)
    <BugTask ...>

    >>> tasks = sorted(
    ...     bug_one.bugtasks, key=by_bugtargetdisplayname)

    >>> for task in tasks:
    ...     print task.target.bugtargetdisplayname
    Mozilla Firefox
    Mozilla Firefox trunk
    mozilla-firefox (Debian)
    mozilla-firefox (Ubuntu)
    thunderbird (Ubuntu)

When we approve the nomination, two more Ubuntu tasks are added for the
Grumpy series. The user that made the decision is stored in the decider
attribute. The date on which the decision was made is stored in the
date_decided attribute.

(Again, first we'll set the driver with an admin user, to ensure
no_privs can actually approve the nomination.)

    >>> login("foo.bar@canonical.com")
    >>> grumpy_nomination.target.driver = no_privs
    >>> login("no-priv@canonical.com")

    >>> grumpy_nomination.date_decided is None
    True
    >>> grumpy_nomination.approve(no_privs)
    >>> print grumpy_nomination.status.title
    Approved
    >>> print grumpy_nomination.decider.name
    no-priv
    >>> grumpy_nomination.date_decided
    datetime...

    >>> tasks = sorted(
    ...     bug_one.bugtasks, key=by_bugtargetdisplayname)

    >>> for task in tasks:
    ...     print task.target.bugtargetdisplayname
    Mozilla Firefox
    Mozilla Firefox trunk
    mozilla-firefox (Debian)
    mozilla-firefox (Ubuntu Grumpy)
    mozilla-firefox (Ubuntu)
    thunderbird (Ubuntu Grumpy)
    thunderbird (Ubuntu)

Let's now nominate for Warty. no_privs is the driver, so will have
no problems.

    >>> ubuntu_warty = ubuntu.getSeries("warty")
    >>> login("foo.bar@canonical.com")
    >>> ubuntu_warty.driver = no_privs
    >>> login("no-priv@canonical.com")

    >>> warty_nomination = bug_one.addNomination(
    ...     target=ubuntu_warty, owner=no_privs)
    >>> warty_nomination.approve(no_privs)

    >>> print warty_nomination.status.title
    Approved
    >>> print warty_nomination.decider.name
    no-priv
    >>> warty_nomination.date_decided
    datetime...

    >>> tasks = sorted(
    ...     bug_one.bugtasks, key=by_bugtargetdisplayname)

    >>> for task in tasks:
    ...     print task.target.bugtargetdisplayname
    Mozilla Firefox
    Mozilla Firefox trunk
    mozilla-firefox (Debian)
    mozilla-firefox (Ubuntu Grumpy)
    mozilla-firefox (Ubuntu Warty)
    mozilla-firefox (Ubuntu)
    thunderbird (Ubuntu Grumpy)
    thunderbird (Ubuntu Warty)
    thunderbird (Ubuntu)

    >>> login("foo.bar@canonical.com")
    >>> ubuntu_warty.driver = None


== Declining a nomination ==

Declining a nomination simply sets its status to DECLINED. No tasks are
created.

    >>> login("foo.bar@canonical.com")
    >>> ubuntu_breezy_autotest_nomination.target.driver = no_privs
    >>> login("no-priv@canonical.com")

    >>> ubuntu_breezy_autotest_nomination.date_decided is None
    True
    >>> print ubuntu_breezy_autotest_nomination.status.title
    Nominated

    >>> ubuntu_breezy_autotest_nomination.decline(no_privs)

    >>> print ubuntu_breezy_autotest_nomination.status.title
    Declined

    >>> ubuntu_breezy_autotest_nomination.isDeclined()
    True
    >>> ubuntu_breezy_autotest_nomination.isApproved()
    False
    >>> ubuntu_breezy_autotest_nomination.isProposed()
    False
    >>> print ubuntu_breezy_autotest_nomination.decider.name
    no-priv
    >>> ubuntu_breezy_autotest_nomination.date_decided
    datetime...


== Automatic targeting of new source packages ==

If a another distribution task is added, and nomination for that
distribution's series already exists, the nominations will be valid
for the new task as well, and bugtasks will be created for all accepted
ones.

The nominations are per distroseries, they are not source package
specific, so they are automatically valid for new bugtasks. What's
important are the accepted nominations. Bug one has an accepted
nomination for Grumpy and Warty:

    >>> accepted_nominations = [
    ...     nomination for nomination in bug_one.getNominations(ubuntu)
    ...     if nomination.isApproved()]
    >>> for nomination in accepted_nominations:
    ...     print nomination.distroseries.displayname
    Grumpy
    Warty

So if we create a new bugtask on evolution (Ubuntu), a task for
evolution (Ubuntu Grumpy) and evolution (Ubuntu Warty) will be created
automatically.

    >>> ubuntu_evolution = ubuntu.getSourcePackage('evolution')
    >>> getUtility(IBugTaskSet).createTask(
    ...     bug=bug_one, owner=no_privs,
    ...     distribution=ubuntu,
    ...     sourcepackagename=ubuntu_evolution.sourcepackagename)
    <BugTask ...>

    >>> tasks = sorted(
    ...     bug_one.bugtasks, key=by_bugtargetdisplayname)

    >>> for task in tasks:
    ...     print task.target.bugtargetdisplayname
    evolution (Ubuntu Grumpy)
    evolution (Ubuntu Warty)
    evolution (Ubuntu)
    ...


== Changing the Source Package of a Targeted Bugtask ==

The nomination model requires that a generic distribution task exists
for each distroseries task. This causes some problem when renaming the
source package on an accepted nomination. For example, if we would
change the thunderbird package on the Grumpy task, it won't have a
corresponding generic distribution task.

The way we tie nominations to distribution series, and not to source
packages, makes it hard to solve source package changes in a nice way.
So what happens when a source package is changed is that we simply
rename all other bugtasks which points to the same distribution and
source package name.  This is not ideal, but hopefully package renames
after the bug has been targeted to a series is rare enough for this to
be acceptable.

    >>> thunderbird_grumpy = tasks[-3]
    >>> thunderbird_grumpy.bugtargetname
    u'thunderbird (Ubuntu Grumpy)'

    >>> thunderbird_grumpy.transitionToTarget(
    ...     ubuntu.getSeries('grumpy').getSourcePackage('pmount'))

    >>> tasks = sorted(
    ...     bug_one.bugtasks, key=by_bugtargetdisplayname)

    >>> for task in tasks:
    ...     print task.target.bugtargetdisplayname
    evolution (Ubuntu Grumpy)
    evolution (Ubuntu Warty)
    evolution (Ubuntu)
    Mozilla Firefox
    Mozilla Firefox trunk
    mozilla-firefox (Debian)
    mozilla-firefox (Ubuntu Grumpy)
    mozilla-firefox (Ubuntu Warty)
    mozilla-firefox (Ubuntu)
    pmount (Ubuntu Grumpy)
    pmount (Ubuntu Warty)
    pmount (Ubuntu)

The same is done if the distribution task's source package is changed.

    >>> pmount_ubuntu = tasks[-1]
    >>> pmount_ubuntu.bugtargetname
    u'pmount (Ubuntu)'

    >>> ubuntu_thunderbird = ubuntu.getSourcePackage('thunderbird')
    >>> pmount_ubuntu.transitionToTarget(ubuntu_thunderbird)

    >>> tasks = sorted(
    ...     bug_one.bugtasks, key=by_bugtargetdisplayname)

    >>> for task in tasks:
    ...     print task.target.bugtargetdisplayname
    evolution (Ubuntu Grumpy)
    evolution (Ubuntu Warty)
    evolution (Ubuntu)
    Mozilla Firefox
    Mozilla Firefox trunk
    mozilla-firefox (Debian)
    mozilla-firefox (Ubuntu Grumpy)
    mozilla-firefox (Ubuntu Warty)
    mozilla-firefox (Ubuntu)
    thunderbird (Ubuntu Grumpy)
    thunderbird (Ubuntu Warty)
    thunderbird (Ubuntu)


== Bug Nomination Set ==

IBugNominationSet is used to fetch bug nominations by ID. This is useful
mainly in traversal code.

    >>> from lp.bugs.interfaces.bugnomination import IBugNominationSet

    >>> getUtility(IBugNominationSet).get(1)
    <BugNomination at ...>

If a nomination is not found, a NotFoundError is raised.

    >>> getUtility(IBugNominationSet).get(-1)
    Traceback (most recent call last):
      ...
    NotFoundError: ...


== Error Handling ==

Trying to nominate a bug for a series for which it's already nominated
or targeted raises a NominationError.

    >>> bug_one.addNomination(
    ...     target=ubuntu_grumpy, owner=no_privs)
    Traceback (most recent call last):
      ..
    NominationError: ...

    >>> bug_one.addNomination(
    ...     target=firefox_trunk, owner=no_privs)
    Traceback (most recent call last):
      ..
    NominationError: ...

Nominating a bug for an obsolete distroseries raises a
NominationSeriesObsoleteError. Let's make a new obsolete distroseries
to demonstrate.

    >>> from lp.registry.interfaces.series import SeriesStatus

    >>> login("foo.bar@canonical.com")
    >>> ubuntu_edgy = factory.makeDistroRelease(
    ...     distribution=ubuntu, version='6.10',
    ...     status=SeriesStatus.OBSOLETE)
    >>> login("no-priv@canonical.com")

    >>> bug_one.addNomination(target=ubuntu_edgy, owner=no_privs)
    Traceback (most recent call last):
      ..
    NominationSeriesObsoleteError: ...

    >>> logout()