Extension Point : ITicketGroupStatsProvider

Interface	ITicketGroupStatsProvider	Since	0.11
Module	trac.ticket.roadmap	Source	roadmap.py​

The ITicketGroupStatsProvider allows components to provide alternate ways to compute Milestone statistics.

Purpose

The roadmap provides a view on the ticket milestones with aggregated group statistics displayed as a milestone progress bar. The default grouping simply shows the ratio between active and resolved tickets. It is possible to customise the ticket grouping and have multiple ticket statuses shown on the progress bar. Plugins can further customize the roadmap system to modify the milestone completion progress bars by changing the way ticket statistics are collected.

The main purpose for this interface is to allow plugins to incorporate more information into the milestone completion calculations (e.g. tracked hours).

Note that for simply having more ticket groups displayed, a change of configuration is enough and no new plugin is needed.

Usage

Implementing the interface follows the standard guidelines found in TracDev/ComponentArchitecture and of course TracDev/PluginDevelopment.

The component has to be configured as the [milestone] stats_provider (to use it when viewing individual milestones) and / or the [roadmap] stats_provider (to use it when viewing the roadmap). Trac then automatically calls the get_ticket_group_stats method to retrieve a TicketGroupStats object for a given group of tickets.

Typically this consists of these steps:

• Create a new instance by calling stat = TicketGroupStats(title, unit) where:
  • title is the title of the statistic (e.g. 'ticket status' as in Ticket status by milestone).
  • unit is the name of the unit for the statistic (e.g. 'tickets' as in Total number of tickets, or 'hours' as in Total number of hours).
• Calculate some statistics e.g. by quering the database.
• Add intervalls to make up the progress bar by calling stat.add_interval(title, count, qry_args, css_class, overall_completion=None) where:
  • title is the name of this interval displayed in front of the unit name (e.g. 'closed') as in Close tickets).
  • count is the number of units in this interval.
  • qry_args is a dict of extra parameters used in a TracQuery to link to tickets in this interval.
  • css_class is the css class that will be used to display this interval.
  • overall_completion can optionally be set to True to make this interval count towards overall completion of this group of tickets.
• Call stat.refresh_calcs() to calculate the interval percentages so they add up to 100%, and then return stat.

Examples

Projects might for some reason want to group tickets and see progress by ticket owner, and count only those tickets as completed where the owner is done with all tickets:

from trac.core import Component, implements
from trac.ticket.roadmap import ITicketGroupStatsProvider, TicketGroupStats

class TicketOwnerGroupStats(Component):
    implements(ITicketGroupStatsProvider)
    
    def get_ticket_group_stats(self, ticket_ids):
        total_cnt = len(ticket_ids)
        stat = TicketGroupStats('ticket owner', 'tickets')
        if total_cnt:
            for owner, count, closed in self.env.db_query("""
                    SELECT
                        owner,
                        count(owner),
                        SUM(CASE WHEN status = 'closed' THEN 1 ELSE 0 END) as closed
                    FROM ticket
                    WHERE id IN (%s) GROUP BY owner
                    """ % ",".join(str(x) for x in sorted(ticket_ids))):
                label = owner
                query_args = {'owner': [owner]}
                css_class = owner
                stat.add_interval(label, count, query_args, css_class, count == closed)
        stat.refresh_calcs()
        return stat

Available Implementations

• trac.ticket.roadmap.DefaultTicketGroupStatsProvider:

• ​th:RoadmapHoursPlugin: Shows intervals Worked hours and Remaining hours.
• ​th:SumStatsPlugin: Sums up a configurable custom ticket field.
• ​th:CustomRoadmapPlugin: Automatically customizes CSS.

Additional Information and References

• ​epydoc
• ​API Reference
• Related tickets:
  • #6232 refactor DefaultTicketGroupStatsProvider so subclasses could easily reuse some parts of its logic.
  • #1534 weighted tickets for progress bar.
• Archived discussions:
  • ​Discussions ​during ​development

API History

• 0.11 introduced the interface (#2314)
• 0.12 removed the deprecated countsToProg argument to TicketGroupStats.add_interval().