WorkItemsHowto

Intro

Several teams now use burn down charts to track the progress of their work, so that they can see when they are falling behind, and decisions such as "this blueprint needs to be postponed" can be done as early as possible.

What is a work item?

A blueprint describes an entire goal or project, can sometimes take many weeks to complete, and can need more than just one person to implement it. For efficient tracking, these need to be broken down to several steps, each of which should not take more than two days. Items which need longer should be split either logically, or if that's impossible, artificially like "do something 1", "do something 2", etc.

One work item has :

  • precisely one assignee who is responsible for it
  • a status (todo, blocked, inprogress, done, postponed)

Defining work items

Two methods of adding work items to a blueprint are currently supported: they can be added by linking bugs from the blueprint using the Link a bug report link, or by recording them in the blueprint's whiteboard. Where applicable, linking to a bug is preferred because this permits integration with the full package and bug management workflows and doesn't require any editing of the blueprint whiteboard to update status. However, some work items don't map well to bug reports on packages, so both methods are supported.

Work items in the whiteboard

The start is indicated by a line "Work items:" (anywhere in the whiteboard), then exactly one line for each work item, and finally an empty line to end the work item list. Each work item is one line with the description, then a colon, and the status, and optionally has an assignee prefix (which should be the Launchpad account name) in square brackets:

  • Work items:
    package gnome-monster: DONE
    write gnome-monster MIR: TODO
    [seb128] patch gnome-monster to support green monsters: POSTPONED
    
    platform, 2009-11-27: can you please clarify the precise shade of green for the proposed patch?
    [.. further whiteboard discussion here... ]

Valid states:

state

possible aliases

description*

TODO

empty string, INPROGRESS

Item is expected to be done by the end of the cycle

INPROGRESS

By default, this is an alias for TODO, but teams can choose to track it separately.

BLOCKED

Item is still expected to be done by end of cycle, but cannot move forward due to issues outside assignees control

DONE

POSTPONED

POSTPONE

item will not be done this cycle

(capitalization does not matter)

* these are just suggestions based on the association with bugs. these states can be used any way you like.

The default assignee for a work item is the blueprint assignee. Use the [assignee] description syntax for blueprints where several people are involved.

Please see desktop-karmic-network-ui for an example.

Work items as linked bugs

Each bug linked from a blueprint will be inspected, and each Ubuntu task on the bug, either on an Ubuntu package or on the Ubuntu distribution (no package assigned), will be treated as a work item, with two exceptions:

  • Tasks with a status of 'Invalid' are ignored and not treated as work items.
  • If a bug includes tasks for multiple distroseries, only one work item is generated for each source package. If a task is present for the current devel distroseries and is not marked "Won't Fix", that task's status will be used; otherwise, the task not qualified by distroseries will be used.

Milestone targets and assignees are taken from the usual bug task fields.

Task states are derived from the bug status, as follows:

bug status

state

New, Incomplete, Confirmed, Triaged

TODO

In Progress, Fix Committed

INPROGRESS

Fix Released

DONE

Won't Fix

POSTPONED

Setting up blueprints

For work item tracking to actually work, blueprints need to

  • have an assignee (unless all of the work items explicitly specify one)
  • need to be targetted to a particular distribution release (this is both a good tool to postpone blueprints later on by untargetting, and also avoids work item scanner exploding on trying to scan a gazillion blueprints)
  • can optionally be targetted to a particular milestone, if the development cycle is divided into several subcycles
  • The whiteboard can have a separate "Status:" area, which describes the overal status in more detail. These are copied verbatim to the "status" column in the generated report. As with work items, the status area ends with an empty line.

Subcycle tracking

Due to dropping the alphas and only having one beta and the release candidate, the development cycle is now divided by time based milestones. For blueprints which can't/are not meant to be finished within one subcycle, it is recommended to split the work items in several blocks, each with a Work items for ubuntu-13.04-month-4: like heading. The milestone name must be exactly like in Launchpad (i. e. not Month 2, m2)

For a full cycle report, all blocks which match work items.*: are counted. (Capitalization is irrelevant)

Example:

  • Work items for ubuntu-13.04-month-4:
    package gnome-monster: DONE
    
    Work items for ubuntu-13.04-beta-1:
    write gnome-monster MIR: TODO
    
    Work items:
    [seb128] patch gnome-monster to support green monsters: POSTPONED

If there is no (valid) milestone in the work items.*: line, they will be assigned to the milestone of the entire blueprint. Thus, if you do not have work items spanning across several subcycles, using "work items:" and properly milestoning the blueprint will do the right and intuitive thing.

Complexity / Story points

To make planning more precise and useful, the Work Item tracker now also supports Complexity Points as known from the Agile Development methodology. These can be used to measure the relative difficulty of a blueprint and manage your velocity. You can read here about Complexity Points and how to assign them.

Complexity points are supported on a per-user, per-milestone granularity. Example:

  • Complexity:
    [bob] maverick-alpha2: 1
    [bob] maverick-alpha3: 4
    [joe] maverick-alpha3: 2

The complexity points will show up in the reports as described below.

Reports

The current reports are generated hourly by team, release, and milestone on http://status.ubuntu.com/. Older reports are at http://people.canonical.com/~platform/workitems/.

Generator scripts

The launchpad-work-items-tracker project contains scripts to process those work items and generate reports:

  • collect scans blueprints of a particular release and puts them into a database, which stores the status of all work items on every date, spec status/descriptions/priority, milestones, and team structure.

  • html-report generates a HTML report with a by-blueprint, by-assignee, and by-workitem list.

  • burndown-chart generates a burn down chart.

  • generate-all iterates over all available milestones and teams and builds reports and burndown charts for all combinations.

  • all-projects iterates over all config/*.cfg and calls collect and generate-all on them. It also does some maintenance jobs like publishing the database to the WWW directory and making daily backups. It's primarily meant to be called from cron on an hourly basis.

The configuration for a particular report set is kept in a single file. See config/lucid.cfg in the bzr branch for an example of the Canonical team report for the Ubuntu Lucid release. These reports are generated with

  •  ./collect -d ~/workitems/lucid.db -c config/lucid.cfg
     ./generate-all -d ~/workitems/lucid.db -c config/lucid.cfg -o ~/public_html/workitems/

Please note that to generate the burndown chart image you will need to install python-pychart, python-mako, and python-storm.

Please contact Martin Pitt for questions, or if you need to change the configuration and cannot commit to the branch yourself.

WorkItemsHowto (last edited 2013-09-05 12:34:53 by chipaca)