[[PageOutline(2-5,Contents,pullout)]]
= Tools for visualizing and quick editing of effort estimations =
== Description ==
!EstimationTools includes macros that visualize remaining effort estimations, e.g., as Burndown Chart, as well as an extension that allows inline editing of estimations in the query view.
== Requirements ==
The charts use [http://code.google.com/apis/chart/ Google's Chart API], hence no additional python modules are required. The [EstimationToolsPlugin#HoursInPlaceEditor HoursInPlaceEditor] requires the XmlRpcPlugin.
== Bugs/Feature Requests ==
Existing bugs and feature requests for EstimationToolsPlugin are
[report:9?COMPONENT=EstimationToolsPlugin here].
If you have any issues, create a
[http://trac-hacks.org/newticket?component=EstimationToolsPlugin&owner=hoessler new ticket].
== Download ==
Download the zipped source from [download:estimationtoolsplugin here].
== Source ==
You can check out EstimationToolsPlugin from [http://trac-hacks.org/svn/estimationtoolsplugin here] using Subversion, or [source:estimationtoolsplugin browse the source] with Trac.
== Install ==
* Trac 0.11.x and Trac 0.12.x is supported in [http://trac-hacks.org/svn/estimationtoolsplugin/trunk trunk].
* The latest version for Trac 0.10 can be checked out [http://trac-hacks.org/svn/estimationtoolsplugin/branches/0.10 here].
* Deploy the egg:
{{{
# python setup.py bdist_egg
# cp dist/*.egg /path/to/trac/env/plugins
}}}
Please see [http://trac.edgewall.org/wiki/TracPlugins Trac's plug-in installation instructions] for more details.
* You need to add a custom field in your trac.ini to store the estimations for the current remaining effort:
{{{
[ticket-custom]
estimatedhours = text
estimatedhours.label = Remaining Hours
estimatedhours.value = 0
}}}
* enable the plugin
{{{
[components]
estimationtools.* = enabled
}}}
* further configurations go here
{{{
[estimation-tools]
# if you want to use another field than estimatedhours you can change that
estimation_field = estimatedhours
# Set to a comma separated list of workflow states
# that count as zero in BurnDownChart. Defaults to 'closed'
closed_states = closed,another_state
# Suffix used for estimations. Defaults to 'h'
estimation_suffix = points
# If you want charts to be served from the server set to true. Useful for SSL connections. Default 'false'
serverside_charts = false
}}}
== Features ==
=== !BurndownChart ===
Creates burn down chart for selected tickets.
This macro creates a chart that can be used to visualize the progress in a milestone (e.g., sprint or
product backlog).
For a given set of tickets and a time frame, the remaining estimated effort is calculated.
The macro has the following parameters:
* a comma-separated list of query parameters for the ticket selection, in the form "key=value" as specified in TracQuery#QueryLanguage.
* `startdate`: '''mandatory''' parameter that specifies the start date of the period (ISO8601 format)
* `enddate`: end date of the period. If omitted, it defaults to either the milestones (if given) `completed' date,
or `due` date, or today (in that order) (ISO8601 format)
* `weekends`: include weekends in chart. Defaults to `true`
* `title`: chart title. Defaults to first milestone or 'Burndown Chart'
* `expected`: show expected progress in chart, 0 or any number to define initial expected hours (defaults to 0).
* `gridlines`: show gridlines in chart, 0 or any number to define hour steps (defaults to 0)
* `width`: width of resulting diagram (defaults to 800)
* `height`: height of resulting diagram (defaults to 200)
* `color`: color specified as 6-letter string of hexadecimal values in the format `RRGGBB`.
Defaults to `ff9900`, a nice orange.
* `colorexpected`: color for expected hours graph specified as 6-letter string of hexadecimal values in the format `RRGGBB`.
Defaults to ffddaa, a nice yellow.
* `bgcolor`: chart drawing area background color specified as 6-letter string of hexadecimal values in the format `RRGGBB`.
Defaults to `ffffff`.
* `wecolor`: chart drawing area background color for weekends specified as 6-letter string of hexadecimal values in the format `RRGGBB`.
Defaults to `ccccccaa`.
Examples:
{{{
[[BurndownChart(milestone=Sprint 1, startdate=2008-01-01)]]
[[BurndownChart(milestone=Release 3.0|Sprint 1, startdate=2008-01-01, enddate=2008-01-15,
weekends=false, expected=100, gridlines=20, width=600, height=100, color=0000ff)]]
}}}
{{{
#!html
}}}
=== !HoursRemaining ===
Calculates remaining estimated hours for the queried tickets.
The macro accepts a comma-separated list of query parameters for the ticket selection,
in the form "key=value" as specified in TracQuery#QueryLanguage.
Example:
{{{
[[HoursRemaining(milestone=Sprint 1)]]
}}}
=== !WorkloadChart ===
Creates workload chart for the selected tickets.
This macro creates a pie chart that shows the remaining estimated workload per ticket owner,
and the remaining work days.
It has the following parameters:
* a comma-separated list of query parameters for the ticket selection, in the form "key=value" as specified in TracQuery#QueryLanguage.
* `width`: width of resulting diagram (defaults to 400)
* `height`: height of resulting diagram (defaults to 100)
* `color`: color specified as 6-letter string of hexadecimal values in the format `RRGGBB`.
Defaults to `ff9900`, a nice orange.
Examples:
{{{
[[WorkloadChart(milestone=Sprint 1)]]
[[WorkloadChart(milestone=Sprint 1, width=600, height=100, color=00ff00)]]
}}}
{{{
#!html
}}}
=== !HoursInPlaceEditor ===
This component allows to edit the remaining hours field directly in the custom query view as well as in the report view.
[[Image(HoursInPlaceEditor.png)]]
* to show the remaining hours in the custom query view, you have to enable the corresponding column
* if you want to show the remaining hours column in your SQL reports, you need to join the ticket table with the ticket_custom table, which contains the custom fields.
{{{
SELECT
... # normal SELECT statement
id AS ticket,
COALESCE(tc.value,'') as estimatedhours, # adds the value of estimatedhours in a column that must have same name original field
FROM ticket t
LEFT JOIN ... # other LEFT JOIN statements (in the default Trac queries) can be left in place
LEFT JOIN ticket_custom tc ON tc.ticket = t.id and tc.name = 'estimatedhours'
...
}}}
* You could change {{{''}}} to '0' to show 0 hours for tickets that don't have a corresponding estimated hours field.
* Tickets may have an estimated hours field that is empty, in which case you may still see "blank"
* See #4549 for a more complex example
viola: Using EstimationToolsPlugin, one can schedule tickets of a project with SchedulingToolsPlugin - try it!
== Recent Changes ==
[[ChangeLog(estimationtoolsplugin, 3)]]
== Author/Contributors ==
'''Author:''' [wiki:hoessler] [[BR]]
'''Contributors:''' [wiki:osimons]