[[PageOutline(2-5,Contents,pullout)]]

= Sums specified field in Roadmap and Milestone stats

== Description

This plugin combines the fields for the roadmap and milestone views. This is a complement to the [wiki:SumFieldsPlugin Sum Fields plugin], which sums fields in a query or report. These plugins are useful when assessing progress based on "points" or "ideal days" of effort instead of ticket count.

[[Image(sumstats.png, border=2)]]

This plugin now also provides a [https://developers.google.com/chart/?csw=1&safe=on Google Visualization API] data source that can populate a burndown chart on milestone pages such as provided by the Trac [wiki:VisualizationPlugin#Burndownchartonmilestonepages Visualization plugin]. See more details [wiki:SumStatsPlugin#Burndownchartdatasource below].

This plugin was inspired by the CustomRoadmapPlugin but overcomes its limitation of requiring a patch. Additionally, this plugin allows for any field to be used to define a group, not just the default {{{status}}} field. Lastly, this plugin was designed to be backward compatible with the default ticket count behavior, so that you can utilise as much or as little of its enhancements as required.

The plugin also provides a [https://developers.google.com/chart/?csw=1&safe=on Google Visualization API] data source at {{{/sumstats/query}}} that can populate a burndown chart. See [wiki:SumStatsPlugin#GoogleVisualizationAPIDataSource-forBurndownChart below] for an example.

== Bugs/Feature Requests

Existing bugs and feature requests for SumStatsPlugin are 
[report:9?COMPONENT=SumStatsPlugin here].

If you have any issues, create a 
[/newticket?component=SumStatsPlugin new ticket].

[[TicketQuery(component=SumStatsPlugin&group=type,format=progress)]]

== Download

Download the zipped source from [export:sumstatsplugin here].

== Source

You can check out SumStatsPlugin from [/svn/sumstatsplugin here] using Subversion, or [source:sumstatsplugin browse the source] with Trac.

== Installation and Configuration

 1. Install the plugin, after downloading and unzipping:
    {{{#!sh
cd sumstatsplugin/0.12
sudo python setup.py install
}}}

 See TracPlugins for more installation details and options. You will likely need to restart Trac's web server after installation.

 2. Enable the plugin in your `trac.ini` file:
    {{{#!ini
[components]
sumstats.* = enabled
}}}

 You can alternatively use the Trac Web Admin GUI.

 3. Replace the {{{DefaultTicketGroupStatsProvider}}} with this plugin's new {{{SumTicketGroupStatsProvider}}} in `trac.ini`:
    {{{#!ini
[roadmap]
stats_provider = SumTicketGroupStatsProvider

[milestone]
stats_provider = SumTicketGroupStatsProvider
}}}

 4. (Optional) Configure the main {{{sumstats}}} section in `trac.ini`:
    {{{#!ini
[sumstats]
field = effort
label = effort
drilldown_label = Ticket effort
filter = type!=epic
query_args = col=summary,col=type,col=effort
}}}

 The optional {{{field}}} option specifies which field to sum. The optional {{{drilldown_label}}} and {{{label}}} options are used to define the {{{TicketGroupStats}}} object. The optional {{{filter}}} is a list of additional global filters for all groups (if specified it's currently limited to standard fields only). The optional {{{query_args}}} is a convenient, comma-delimited list that gets appended to each group's {{{query_args}}}. See the examples below for more details.

 5. (Optional) Install the [https://developers.google.com/chart/interactive/docs/dev/gviz_api_lib?csw=1&safe=on Google Visualization API Python gviz client library] if using as a data source, see [wiki:SumStatsPlugin#GoogleVisualizationAPIDataSource-forBurndownChart below].

== Examples

=== Combining resolution and phase fields

Here is a sample `trac.ini` file that combines a custom {{{phase}}} field with a standard {{{resolution}}} field:
{{{#!ini
[milestone-groups]
closed = fixed
closed.field = resolution
closed.label = fixed
closed.order = 1
closed.overall_completion = true

readying = *
readying.field = phase
readying.order = 2
readying.color = YellowGreen

implementation = implementation
implementation.field = phase
implementation.order = 3
implementation.color = Yellow

waiting = waiting
waiting.field = phase
waiting.order = 4
waiting.color = White

scoping = sizing,definition
scoping.field = phase
scoping.order = 5
scoping.color = Red
}}}

This plugin maintains the same syntax and semantics as the {{{DefaultTicketGroupStatsProvider}}} to support backwards compatibility and ease of transition. If the {{{.field}}} option is omitted, then the {{{status}}} field is presumed. Note that a {{{.color}}} option is required for each group (except for any default {{{closed}}} or {{{new}}} group you have). The "catch all" {{{*}}} value is also supported, although there are currently no checks for duplicate "catch all" or otherwise redundant group definitions.

=== Burndown chart data source

This plugin also provides a Google Visualization API data source using the [https://developers.google.com/chart/interactive/docs/dev/gviz_api_lib?csw=1&safe=on Python Gviz client library] (which must be installed separately) that can populate a daily, agile-style [http://en.wikipedia.org/wiki/Burn_down_chart burndown chart]. Being a standard Google Visualization API data source, it can be accessed and visualized anywhere. However, it can also display burndown charts on Trac milestone pages by using the Trac [wiki:VisualizationPlugin#Burndownchartonmilestonepages Visualization plugin], for example:

[[Image(burndown.png)]]

The data source reuses the {{{filter}}} option set in the {{{[sumstats]}}} section. See step 4 of the [wiki:SumStatsPlugin#Configuration Configuration section above] for more details. No additional configuration is required to enable the burndown data source. However, it currently makes the following assumptions:

 * "done" means closed as {{{fixed}}}
 * if a sum field is provided, then it's assumed to be a custom field (not a standard field)
 * if the milestone cannot be extracted from the referrer url, then the current milestone is assumed.

The data is accessed at:

`http://<your-trac-domain>/sumstats/query`

The above request returns a data table (in JSON response format) of up to 4 columns:

 * {{{day}}} - the day
 * {{{total}}} - the total sum or count for the day (both marked as {{{fixed}}} and not closed)
 * {{{todo}}} - the remaining (i.e., not closed) sum or count for the day
 * {{{done}}} - the completed (i.e., closed as {{{fixed}}}) sum or count for the day

The default response includes the {{{day}}}, {{{todo}}} and {{{done}}} fields in that order. To change which fields are returned and/or their order, eg to display the data in alternatively configured charts, you can add a (partial) query, ie the {{{tq}}} portion below:

`http://<your-trac-domain>/sumstats/query?tq=select total,done`

Only the select phrase is used at this time to specify which columns to return and their order. The {{{day}}} field is always the first column and should be omitted from the select phrase. You may need to urlencode the {{{tq}}} value.

Let me know if you need additional flexibility in the query and I'll consider adding it. For example, ways to specify the milestone explicitly, a different timeframe grouping than daily, etc.

== Recent Changes

[[ChangeLog(sumstatsplugin, 3)]]

== Author/Contributors

'''Author:''' [wiki:robguttman] [[BR]]
'''Maintainer:''' [[Maintainer]] [[BR]]
'''Contributors:'''