trac.ticket.roadmap – The Roadmap and Milestone modules

The component responsible for the Roadmap feature in Trac is the RoadmapModule. It provides an overview of the milestones and the progress in each of these milestones.

The component responsible for interacting with each milestone is the MilestoneModule. A milestone also provides an overview of the progress in terms of tickets processed.

The grouping of tickets in each progress bar is governed by the use of another component implementing the ITicketGroupStatsProvider interface. By default, this is the DefaultTicketGroupStatsProvider (for both the RoadmapModule and the MilestoneModule), which provides a configurable way to specify how tickets are grouped.

Interfaces

class trac.ticket.roadmap.ITicketGroupStatsProvider

Bases: trac.core.Interface

See also trac.ticket.roadmap.ITicketGroupStatsProvider extension point

get_ticket_group_stats(ticket_ids)

Gather statistics on a group of tickets.

This method returns a valid TicketGroupStats object.

class trac.ticket.roadmap.TicketGroupStats(title, unit)

Bases: object

Encapsulates statistics on a group of tickets.

Parameters:
  • title – the display name of this group of stats (e.g. 'ticket status')
  • unit – is the units for these stats in plural form, e.g. _('hours')
add_interval(title, count, qry_args, css_class, overall_completion=None)

Adds a division to this stats’ group’s progress bar.

Parameters:
  • title – the display name (e.g. 'closed', 'spent effort') of this interval that will be displayed in front of the unit name
  • count – the number of units in the interval
  • qry_args – a dict of extra params that will yield the subset of tickets in this interval on a query.
  • css_class – is the css class that will be used to display the division
  • overall_completion – can be set to true to make this interval count towards overall completion of this group of tickets.

Changed in version 0.12: deprecated countsToProg argument was removed, use overall_completion instead

Components

class trac.ticket.roadmap.MilestoneModule

Bases: trac.core.Component

View and edit individual milestones.

default_group_by

Default field to use for grouping tickets in the grouped progress bar. (‘’since 1.2’‘)

get_default_due(req)

Returns a datetime object representing the default due date in the user’s timezone. The default due time is 18:00 in the user’s time zone.

stats_provider

Name of the component implementing ITicketGroupStatsProvider, which is used to collect statistics on groups of tickets for display in the milestone views.

class trac.ticket.roadmap.RoadmapModule

Bases: trac.core.Component

Give an overview over all the milestones.

stats_provider

Name of the component implementing ITicketGroupStatsProvider, which is used to collect statistics on groups of tickets for display in the roadmap views.

class trac.ticket.roadmap.DefaultTicketGroupStatsProvider

Bases: trac.core.Component

Configurable ticket group statistics provider.

See TracIni#milestone-groups-section for a detailed example configuration.

Helper Functions

trac.ticket.roadmap.apply_ticket_permissions(env, req, tickets)

Apply permissions to a set of milestone tickets as returned by get_tickets_for_milestone().

trac.ticket.roadmap.get_tickets_for_milestone(env, milestone=None, field='component')

Retrieve all tickets associated with the given milestone.

trac.ticket.roadmap.grouped_stats_data(env, stats_provider, tickets, by, per_group_stats_data)

Get the tickets stats data grouped by ticket field by.

per_group_stats_data(gstat, group_name) should return a data dict to include for the group with field value group_name.

trac.ticket.roadmap.get_num_tickets_for_milestone(env, milestone, exclude_closed=False)

Returns the number of tickets associated with the milestone.

Parameters:
  • milestone – name of a milestone or a Milestone instance.
  • exclude_closed – whether tickets with status ‘closed’ should be excluded from the count. Defaults to False.
Since:

1.2
trac.ticket.roadmap.group_milestones(milestones, include_completed)

Group milestones into “open with due date”, “open with no due date”, and possibly “completed”. Return a list of (label, milestones) tuples.