~launchpad-pqm/launchpad/devel

= ProductSeries =

A Launchpad Product models a single piece of software. However for

release management purposes, a Product often has to be split in several

discrete entities which must be considered separately for packaging,

translations, version control, etc. We call these entities

ProductSeries.

    >>> from zope.component import getUtility

    >>> from lp.services.webapp.testing import verifyObject

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

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

    >>> from lp.registry.interfaces.productseries import IProductSeries

    >>> from lp.translations.interfaces.hastranslationimports import (

    ...     IHasTranslationImports)

    >>> from lp.services.database.sqlbase import flush_database_updates

First, get a product that has some ProductSeries in the sample data.

    >>> productset = getUtility(IProductSet)

    >>> firefox = productset['firefox']

A ProductSeries can be retrieved using the associated product and the

series name.

    >>> trunk = firefox.getSeries('trunk')

Verify that the resulting object correctly implements the IProductSeries

interface.

    >>> verifyObject(IProductSeries, trunk)

    True

    >>> IProductSeries.providedBy(trunk)

    True

and IHasTranslationImports.

    >>> verifyObject(IHasTranslationImports, trunk)

    True

    >>> IHasTranslationImports.providedBy(trunk)

    True

And verify that it looks like the series we think it should be.

    >>> trunk.product == firefox

    True

    >>> print trunk.name

    trunk

It's also possible to ask a product for all its associated series.

    >>> onedotzero = firefox.getSeries('1.0')

    >>> list(firefox.series) == [onedotzero, trunk]

    True

A ProductSeries can also be fetched with the IProductSeriesSet utility.

    >>> from lp.registry.interfaces.productseries import IProductSeriesSet

    >>> firefox_1_0 = getUtility(IProductSeriesSet).get(2)

    >>> print firefox_1_0.product.name

    firefox

    >>> print firefox_1_0.name

    1.0

New ProductSeries are created using Product.newSeries(). Only the product

owner or driver can call Product.newSeries().

    >>> series_driver = factory.makePerson(name="driver")

    >>> summary = "Port of Firefox to the Emacs operating system."

    >>> emacs = firefox.newSeries(series_driver , 'emacs', summary)

    Traceback (most recent call last):

    ...

    Unauthorized: (..., 'newSeries', 'launchpad.Driver')

    >>> login_person(firefox.owner)

    >>> emacs_series = firefox.newSeries(

    ...     firefox.owner , 'emacs', summary,

    ...     releasefileglob='ftp://gnu.org/emacs*.gz')

    >>> print emacs_series.name

    emacs

    >>> print emacs_series.summary

    Port of Firefox to the Emacs operating system.

    >>> print emacs_series.releasefileglob

    ftp://gnu.org/emacs*.gz

When a driver creates a series, he is also the driver of the new series

to make him the release manager.

    >>> firefox.driver = series_driver

    >>> login_person(series_driver)

    >>> emacs2 = firefox.newSeries(series_driver , 'emacs2', summary)

    >>> print emacs2.driver.name

    driver

A newly created series is assumed to be in the development state.

    >>> login(ANONYMOUS)

    >>> print emacs_series.status.title

    Active Development

Let's check that the new series is properly associated to its product.

    >>> flush_database_updates()

    >>> firefox.getSeries('emacs') == emacs_series

    True

= Drivers and release managers =

A driver for an IProduct or IProjectGroup cannot modify a product series.

    >>> from lp.services.webapp.authorization import check_permission

    >>> login_person(series_driver)

    >>> print emacs_series.owner.name

    name12

    >>> print emacs_series.driver

    None

    >>> check_permission('launchpad.Edit', emacs_series)

    False

A person appointed to the series driver has the release manager role and can

edit a product series.

    >>> login_person(firefox.owner)

    >>> emacs_series.driver = series_driver

    >>> login_person(series_driver)

    >>> check_permission('launchpad.Edit', emacs_series)

    True

    >>> login(ANONYMOUS)

== ProductSeries releassefileglob ==

Each ProductSeries may have a releassefileglob that describes the location

of where release files are uploaded to. The product release finder process

uses the releassefileglob to locate and retrieve files. The files are stored

in the librarian. Each fill is associated with a release. If the series

does not have a release for version in the file name, the finder will create

it. The finder will also create the series milestone too if it does not

exist. The success of product release finder to retrieve files, and create

milestone and releases, is largely predicated on the quality of the

releassefileglob.

The field is constrained by the validate_release_glob() function. It verifies

that the url uses one of the supported schemes (ftp, http, http).

    >>> from lp.registry.interfaces.productseries import (

    ...     validate_release_glob)

    >>> validate_release_glob('ftp://ftp.gnu.org/gnu/emacs/emacs-21.*.gz')

    True

    >>> validate_release_glob('http://ftp.gnu.org/gnu/emacs/emacs-21.*.gz')

    True

    >>> validate_release_glob('https://ftp.gnu.org/gnu/emacs/emacs-21.*.gz')

    True

Invalid URLs and unsupported schemes raise a LaunchpadValidationError.

    >>> validate_release_glob('ftp.gnu.org/gnu/emacs/emacs-21.*.gz')

    Traceback (most recent call last):

     ...

    LaunchpadValidationError: ...

    >>> validate_release_glob('wais://ftp.gnu.org/gnu/emacs/emacs-21.*.gz')

    Traceback (most recent call last):

     ...

    LaunchpadValidationError: ...

The URL must contain a glob (*) or , and may contain more than one.

    >>> validate_release_glob('http://ftp.gnu.org/gnu/emacs/emacs-21.10.1.gz')

    Traceback (most recent call last):

     ...

    LaunchpadValidationError: ...

    >>> validate_release_glob('http://ftp.gnu.org/gnu/*/emacs-21.*.gz')

    True

== Specification Listings ==

We should be able to get lists of specifications in different states

related to a productseries.

Basically, we can filter by completeness, and by whether or not the spec

is informational.

    >>> onezero = firefox.getSeries("1.0")

    >>> from lp.blueprints.enums import SpecificationFilter

We will create two specs for onezero and use them to demonstrate the

filtering.

    >>> from lp.services.database.constants import UTC_NOW

    >>> carlos = getUtility(IPersonSet).getByName('carlos')

    >>> from lp.blueprints.model.specification import Specification

    >>> a = Specification(name='a', title='A', summary='AA', owner=carlos,

    ...                   product=firefox, productseries=onezero,

    ...                   specurl='http://wbc.com/two', goal_proposer=carlos,

    ...                   date_goal_proposed=UTC_NOW)

    >>> b = Specification(name='b', title='b', summary='bb', owner=carlos,

    ...                   product=firefox, productseries=onezero,

    ...                   specurl='http://fds.com/adsf', goal_proposer=carlos,

    ...                   date_goal_proposed=UTC_NOW)

Now, we will make one of them accepted, the other declined, and both of

them informational.

    >>> from lp.blueprints.enums import (

    ...     SpecificationDefinitionStatus,

    ...     SpecificationImplementationStatus,

    ...     )

    >>> a.definition_status = b.definition_status = SpecificationDefinitionStatus.APPROVED

    >>> a.implementation_status = SpecificationImplementationStatus.INFORMATIONAL

    >>> b.implementation_status = SpecificationImplementationStatus.INFORMATIONAL

    >>> a.acceptBy(a.owner)

    >>> shim = a.updateLifecycleStatus(a.owner)

    >>> b.declineBy(b.owner)

    >>> shim = b.updateLifecycleStatus(b.owner)

    >>> from lp.services.database.sqlbase import flush_database_updates

    >>> flush_database_updates()

If we ask for ALL specs we should see them both.

    >>> filter = [SpecificationFilter.ALL]

    >>> for s in onezero.specifications(filter=filter):

    ...     print s.name

    a

    b

With a productseries, we can ask for ACCEPTED, PROPOSED and DECLINED

specs:

    >>> filter=[SpecificationFilter.ACCEPTED]

    >>> for spec in onezero.specifications(filter=filter):

    ...     print spec.name, spec.goalstatus.title

    a Accepted

    >>> filter=[SpecificationFilter.PROPOSED]

    >>> onezero.specifications(filter=filter).count()

    0

    >>> filter=[SpecificationFilter.DECLINED]

    >>> onezero.specifications(filter=filter).count()

    1

We should see one informational spec if we ask just for that, the

accepted one.

    >>> filter = [SpecificationFilter.INFORMATIONAL]

    >>> for s in onezero.specifications(filter=filter):

    ...     print s.name

    a

If we specifically ask for declined informational, we will get that:

    >>> filter = [

    ...    SpecificationFilter.INFORMATIONAL, SpecificationFilter.DECLINED]

    >>> for s in onezero.specifications(filter=filter):

    ...     print s.name

    b

There are is one completed, accepted spec for 1.0:

    >>> filter = [SpecificationFilter.COMPLETE]

    >>> for spec in onezero.specifications(filter=filter):

    ...    print spec.name, spec.is_complete, spec.goalstatus.title

    a True Accepted

There is one completed, declined spec:

    >>> filter = [SpecificationFilter.COMPLETE, SpecificationFilter.DECLINED]

    >>> for spec in onezero.specifications(filter=filter):

    ...    print spec.name, spec.is_complete, spec.goalstatus.title

    b True Declined

Now lets make b incomplete, but accepted.

    >>> b.implementation_status = SpecificationImplementationStatus.BETA

    >>> b.definition_status = SpecificationDefinitionStatus.NEW

    >>> shim = b.acceptBy(b.owner)

    >>> shim = b.updateLifecycleStatus(b.owner)

    >>> flush_database_updates()

And if we ask just for specs, we get BOTH the incomplete and the

complete ones that have been accepted.

    >>> for spec in onezero.specifications():

    ...     print spec.name, spec.is_complete, spec.goalstatus.title

    a True Accepted

    b False Accepted

We can search for text in specifications (in this case there are no

matches):

    >>> print len(list(onezero.specifications(filter=['new'])))

    0

== Lifecycle Management ==

In the example above, we use the acceptBy and updateLifecycleStatus methods on

a specification. These help us keep the full record of who moved the spec

through each relevant stage of its existence.

    >>> b.goal_decider is None

    False

    >>> b.goal_decider.name

    u'carlos'

    >>> b.date_completed is None

    True

There's a method which will tell us if status changes we have just made will

change the overall state of the spec to "completed".

    >>> jdub = getUtility(IPersonSet).getByName('jdub')

    >>> b.definition_status = SpecificationDefinitionStatus.APPROVED

    >>> b.implementation_status = SpecificationImplementationStatus.INFORMATIONAL

    >>> print b.updateLifecycleStatus(jdub).title

    Complete

    >>> b.completer.name

    u'jdub'

    >>> b.date_completed is None

    False

== Drivers ==

Products, projects and product series have drivers, who are people that

have permission to approve bugs and features for specific releases. The

rules are that:

 1. a "driver" can be set on either ProjectGroup, Product or ProductSeries

 2. drivers are only actually relevant on a ProductSeries, because thats

    the granularity at which we track spec/bug targeting

 3. the important attribute is ".drivers" on a productseries, it is

    calculated based on the combination of owners and drivers in the

    series, product and project. It is a LIST of drivers, which might be

    empty, or have one, two or three people/teams in it.

 4. the list includes the explicitly set drivers from series, product

    and project

 5. if there are no explicitly set drivers, then:

      - if there is a project, then the list is the project.owner

      - if there is no project, then the list is the product.owner in

    other words, we use the "highest" owner as the fallback, which is

    either the product owner or the project owner if there is a project.

We test these rules below. We will create the project, product and

series directly so that we don't have to deal with security permissions

checks when setting and resetting the driver attributes.

    >>> from lp.services.database.sqlbase import flush_database_updates

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

    >>> carlos = getUtility(IPersonSet).getByName('carlos')

    >>> mark = getUtility(IPersonSet).getByName('mark')

    >>> jblack = getUtility(IPersonSet).getByName('jblack')

    >>> project = factory.makeProject(name='testproj',

    ...     displayname='Test Project',

    ...     title='Test Project Title', homepageurl='http://foo.com/url',

    ...     summary='summary', description='description', owner=carlos)

    >>> product = factory.makeProduct(owner=mark, name='testprod',

    ...     displayname='Test Product', title='Test product title',

    ...     summary='summary', project=project)

    >>> series = factory.makeProductSeries(owner=jblack, name='1.0', product=product,

    ...     summary='Series summary')

First, lets see what we get for the series drivers before we have

anything actually set.

If there is a project on the product, we would expect the project owner:

    >>> print series.product.project.name

    testproj

    >>> for d in series.drivers:

    ...     print d.name

    carlos

If there is NO project on the product, then we expect the product owner:

    >>> product.project = None

    >>> for d in series.drivers:

    ...     print d.name

    mark

Now lets put the project back:

    >>> product.project = project.id

    >>> flush_database_updates()

Edgar and cprov will be the drivers.

    >>> cprov = getUtility(IPersonSet).getByName('cprov')

    >>> edgar = getUtility(IPersonSet).getByName('edgar')

Edgar becomes the driver of the project group and thus also drives the

series.

    >>> project.driver = edgar

    >>> for d in series.drivers:

    ...     print d.name

    edgar

In addition cprov is made driver of the series. Both are drivers now.

    >>> series.driver = cprov

    >>> for d in series.drivers:

    ...     print d.name

    cprov

    edgar

With just a driver on the series, the owner of the project group is reported

as driver, too.

    >>> project.driver = None

    >>> for d in series.drivers:

    ...     print d.name

    carlos

    cprov

Without a project group, the driver role falls back to the product owner.

    >>> product.project = None

    >>> for d in series.drivers:

    ...     print d.name

    cprov

    mark