Editing EstimationToolsPlugin

[[PageOutline(2-5,Contents,pullout)]] = Tools for visualizing and editing of effort estimations == Description This plugin includes macros that visualize remaining effort estimations, eg Burndown Charts, as well as an extension that allows inline editing of estimations in the query view. An explanation of burndown charts and how they fit in a project working environment, is given on [wikipedia:Burndown_chart Wikipedia]. The charts use [https://developers.google.com/chart/?csw=1 Google's Chart API], hence no additional Python modules are required. === !BurndownChart Creates a burndown chart for selected tickets. This macro creates a chart that can be used to visualize the progress in a milestone, eg sprint or product backlog. For a given set of tickets and a time frame, the remaining estimated effort is calculated. {{{ [[BurndownChart([<query>,]<startdate>[,<enddate>][,<weekends>][,<title>][,<expected>][,<gridlines>] [,<width>][,<height>][,<color>][,<colorexpected>][,<bgcolor>][,<wecolor>])]] }}} ==== Parameters The macro has the following arguments and parameters: ||'''Argument'''||'''Description'''||'''Default'''||'''Example'''|| || `query`|| a comma-separated list of query parameters for the ticket selection, in the form "key=value" as specified in TracQuery#QueryLanguage. || || `milestone=2011-05,owner=adrian` || || `startdate`|| [''Required''] specifies the start date of the period `[YYYY-MM-DD ISO-8601 format]` || || `startdate=2011-05-10` || || `enddate`|| end date of the period `[YYYY-MM-DD ISO-8601 format]` || In order (defaults on first given): `milestones` or `completed` date, or `due` date, or `today` || `enddate=2011-05-30` || || `weekends`|| include weekends in chart `[true, false]` || `true` || `weekends=false` || || `title`|| chart title `[accepts non ASCII charset (i.e. à, ü, ñ ...)]` || first milestone or `Burndown Chart` || `title=Estimation Tools Plugin` || || `expected`|| show expected progress in chart `[0 or any number to define initial expected hours]` || `0` || `expected=500` || || `gridlines`|| show gridlines in chart `[0 or any number to define hour steps]` || `0` || `gridlines=100` || || `width`|| width of resulting diagram `[px]` || `800` || `width=450` || || `height`|| height of resulting diagram `[px]` || `200` || `height=150` || || `color`|| burn down graph color `[RRGGBB]` ||`ff9900` (a nice orange) || `color=0099ff` || || `colorexpected`|| color for expected hours graph `[RRGGBB]` || `ffddaa` (a nice yellow) || `colorexpected=ddffdd` || || `bgcolor`|| chart drawing area background color `[RRGGBB]` || `ffffff` || `bgcolor=ccee10` || || `wecolor`|| chart drawing area background color for weekends `[RRGGBB]` ||`cccccc` || `wecolor=10bb20` || Note ^1^:: The arguments can be given in any order. Note ^2^:: `[RRGGBB]` is a 6-character string of hexadecimal values '''Examples:''' :: {{{ [[BurndownChart(milestone=Sprint 1, startdate=2016-01-01)]] [[BurndownChart(milestone=Release 3.0|Sprint 1, startdate=2016-01-01, enddate=2016-01-15, weekends=false, expected=100, gridlines=20, width=600, height=100, color=0000ff)]] }}} '''Results:''' :: {{{#!comment Below follows the almost equivalent code for the above example: }}} {{{#!html <img src="http://chart.apis.google.com/chart?chs=800x200&amp;chd=t:0.0,9.09090909091,18.1818181818,27.2727272727,36.3636363636,45.4545454545,54.5454545455,63.6363636364,72.7272727273,81.8181818182,90.9090909091,100.0|81.0,100.0,99.0,100.0,94.4055944056,85.4055944056,72.4055944056,65.4055944056,62.4055944056,43.4055944056,-1,-1&amp;cht=lxy&amp;chxt=x,x,x,y&amp;chxl=0:|15|16|17|18|19|20|21|22|23|24|25|26|1:|9|9|2:|2016|2016&amp;chxr=3,0,143.0&amp;chm=R,f1f1f1,0,0.40909090909,0.59090909091&amp;chg=100.0,100.0,1,0&amp;chco=ff9900&amp;chtt=Current Sprint" alt='Burndown Chart' /> }}} === !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. {{{ [[HoursRemaining([<query>])]] }}} Note ^3^:: argument is not mandatory, if not given, then it defaults to (T.B.D.)? '''Example:''' :: {{{Remaining effort to conclude this milestone: '''[[HoursRemaining(milestone=Sprint 1)]]''' hs.}}} '''Results:''' :: Remaining effort to conclude this milestone: '''64''' hs. === !WorkloadChart Creates a 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. {{{ [[WorkloadChart([<query>][,<width>][,<height>][,<color>])]] }}} ==== Parameters Supports the following parameters: ||'''Argument'''||'''Description'''||'''Default'''||'''Example'''|| || `query`|| a comma-separated list of query parameters for the ticket selection, in the form "key=value" as specified in TracQuery#QueryLanguage. || || `milestone=2011-05,owner=adrian` || || `width`|| width of resulting diagram `[px]` || `400` || `width=450` || || `height`|| height of resulting diagram `[px]` || `100` || `height=150` || || `color`|| pie chart starting set of color `[RRGGBB]` ||`ff9900` (a nice orange) || `color=00ff00` || Note ^1^:: The arguments can be given in any order. Note ^2^:: `[RRGGBB]` is a 6-character string of hexadecimal values '''Example:''' :: {{{ [[WorkloadChart(milestone=Sprint 1, width=400, height=100, color=00ff00)]] }}} '''Results:''' :: {{{ #!html <img src="http://chart.apis.google.com/chart?chs=400x100&chd=t:12,30,22&cht=p3&chtt=Workload%2064h%20(3%20workdays%20left)&chl=Jane%2012h|Peter%2030h|Jack%2022h&chco=00ff00" alt="Workload Chart"> }}} === !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, border=2)]] '''Notes''': * 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: {{{#!sql 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. Using EstimationToolsPlugin you can schedule tickets of a project with SchedulingToolsPlugin. == Bugs/Feature Requests Existing bugs and feature requests for EstimationToolsPlugin are [report:9?COMPONENT=EstimationToolsPlugin here]. If you have any issues, create a [/newticket?component=EstimationToolsPlugin new ticket]. [[TicketQuery(component=EstimationToolsPlugin,group=type,format=progress)]] == Download Download the zipped source from [export:estimationtoolsplugin here]. There is also an [http://dl.dropbox.com/u/4213259/deb/trac-estimationtools_0.4.5-1_all.deb unofficial Debian package] (source: [http://dl.dropbox.com/u/4213259/deb/trac-estimationtools_0.4.5.orig.tar.gz orig.tar.gz] [http://dl.dropbox.com/u/4213259/deb/trac-estimationtools_0.4.5-1.debian.tar.gz debian.tar.gz] [http://dl.dropbox.com/u/4213259/deb/trac-estimationtools_0.4.5-1.dsc dsc]). The plugin is also available on [pypi:TracEstimationTools PyPI]. == Source You can check out EstimationToolsPlugin from [/svn/estimationtoolsplugin here] using Subversion, or [source:estimationtoolsplugin browse the source] with Trac. == Installation 1. '''Install''' * Trac 0.11.x and Trac 0.12.x is supported in [/svn/estimationtoolsplugin/trunk trunk]. * The latest version for Trac 0.10 can be checked out [/svn/estimationtoolsplugin/branches/0.10 here]. 1. Manually: deploy the egg: {{{#!sh python setup.py bdist_egg cp dist/*.egg /path/to/trac/env/plugins }}} 1. Globally: {{{#!sh easy_install https://trac-hacks.org/svn/estimationtoolsplugin/trunk/ }}} 1. '''Add''' a custom field to the `trac.ini` file to store the estimations for the current remaining effort: {{{#!ini [ticket-custom] estimatedhours = text estimatedhours.label = Remaining Hours estimatedhours.value = 0 }}} 1. '''Enable''' the plugin in the `trac.ini` file: {{{#!ini [components] estimationtools.* = enabled }}} 1. '''Configure''' the plugin at its own configuration section in the `trac.ini` file: {{{#!ini [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 }}} 4. '''Restart''' web server on command line: {{{#!sh sudo /etc/init.d/apache2 restart }}} === Requirements The [EstimationToolsPlugin#HoursInPlaceEditor HoursInPlaceEditor] requires the XmlRpcPlugin. == Recent Changes [[ChangeLog(estimationtoolsplugin, 3)]] == Author/Contributors '''Author:''' [wiki:hoessler] [[BR]] '''Maintainer:''' [[Maintainer]] [[BR]] '''Contributors:''' [wiki:osimons]