= 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 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
}}}
== 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)
* `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.
* `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 `f1f1f1`.
Examples:
{{{
[[BurndownChart(milestone=Sprint 1, startdate=2008-01-01)]]
[[BurndownChart(milestone=Release 3.0|Sprint 1, startdate=2008-01-01, enddate=2008-01-15,
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 query view.
[[Image(HoursInPlaceEditor.png)]]
== Tips ==
=== Customising Queries ===
If you want to show the remaining hours column in your SQL queries, you need to join the ticket table with the ticket_custom table, which contains the custom fields. However, please note that the !HoursInPlaceEditor won't work with these reports, but only with "custom queries".
{{{
SELECT
... # normal SELECT statement
id AS ticket,
ifnull(tc.value,'') as Hrs, # adds the value of estimatedhours in a column called Hrs, using '' if it doesn't exist.
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 Hrs to 'Remaining Hours' to modify the column name.
* You could change {{{''}}} to '0' to show 0 hours for tickets that don't have a corresponding estimatedhours field.
* Tickets may have an estimated hours field that is empty, in which case you may still see "blank"
== Recent Changes ==
[[ChangeLog(estimationtoolsplugin, 3)]]
== Author/Contributors ==
'''Author:''' [wiki:hoessler] [[BR]]
'''Contributors:'''