3 | | = Analyzes tickets for dependency and other problems = |
4 | | |
5 | | == Description == |
6 | | |
7 | | This is an extensible analysis tool for analyzing tickets in reports. This plugin requires !JavaScript and [http://jqueryui.com/ jquery-ui] (included) for the dialog modals. This plugin currently has four built-in analyses: |
8 | | |
9 | | 1. '''Milestone Dependency Analysis''' - ensures dependent tickets are in current or prior milestones |
10 | | 1. '''Queue Dependency Analysis''' - ensures dependent ''peer'' tickets in a queue are ordered correctly |
11 | | 1. '''Project Queue Analysis''' - ensures dependent ''child'' tickets of parent tickets in a queue follow the parents' ordering |
12 | | 1. '''Project Rollup Analysis''' - summarizes (or rolls up) the child tickets' fields in the parent ticket |
13 | | |
14 | | All of the analyses above build upon the [wiki:MasterTicketsPlugin master tickets plugin]. The second and third analyses also build upon the [wiki:QueuesPlugin queues plugin]. (Be sure to use the latest version of the queues plugin so that the included jquery-ui versions match to avoid conflicts!) See below for examples. |
| 3 | = Analyzes tickets for dependency and other problems |
| 4 | |
| 5 | == Description |
| 6 | |
| 7 | This is an extensible analysis tool for analyzing tickets in reports. This plugin requires !JavaScript and [http://jqueryui.com/ jquery-ui] (included) for the dialog modals. This plugin currently has the following built-in analyses: |
| 8 | |
| 9 | 1. '''Milestone Dependency Analysis''' - ensures dependent tickets are in current or prior milestones. |
| 10 | 1. '''Queue Dependency Analysis''' - ensures dependent ''peer'' tickets in a queue are ordered correctly. |
| 11 | 1. '''Project Queue Analysis''' - ensures dependent ''child'' tickets of parent tickets in a queue follow the parents' ordering. |
| 12 | 1. '''Project Rollup Analysis''' - summarizes (or rolls up) the child tickets' fields in the parent ticket. |
| 13 | |
| 14 | All of the analyses above build upon the [wiki:MasterTicketsPlugin master tickets plugin]. The second and third analyses also build upon the [wiki:QueuesPlugin queues plugin]. Be sure to use the latest version of the queues plugin so that the included jquery-ui versions match to avoid conflicts! |
| 15 | |
| 16 | See below for examples. |
18 | | == Configuration == |
19 | | 1. Install the plugin (after downloading and unzipping): |
20 | | {{{ |
21 | | #!sh |
22 | | cd analyzeplugin/0.12 |
23 | | sudo python setup.py bdist_egg |
24 | | sudo cp dist/TracAnalyze*.egg /your/trac/location/plugins/ |
25 | | }}} |
26 | | |
27 | | See [http://trac.edgewall.org/wiki/TracPlugins TracPlugins] for more installation details and options. You'll likely need to restart Trac's web server after installation. |
28 | | |
29 | | 2. Enable the plugin: |
30 | | {{{ |
31 | | #!sh |
32 | | [components] |
33 | | analyze.* = enabled |
34 | | }}} |
35 | | |
36 | | You can alternatively use the Trac Web Admin GUI to enable any or all rules. |
37 | | |
38 | | 3. Enable the {{{ANALYZE_VIEW}}} permission for those users who are allowed to execute analyses. |
39 | | |
40 | | See the examples section [wiki:AnalyzePlugin#Examples below] for how to specify rules. |
41 | | |
42 | | |
43 | | == Bugs/Feature Requests == |
| 20 | == Bugs/Feature Requests |
59 | | == Example == |
60 | | |
61 | | This plugin currently includes four analyses that can each be individually enabled for one or more reports. Each analysis is configured by modifying the {{{[analyze]}}} section of {{{trac.ini}}} - see below for examples. When an analysis is enabled for a report, an '''Analyze...''' button appears at the top of the report and the analysis' name will appear in the subsequent dialog box when the button is clicked. You can either choose a single analysis or all analyses in this dialog box. Selecting "All" will run them serially. |
62 | | |
63 | | '''Important:''' The current analyses are powerful and yet are limited. They do not, for example, detect circular dependencies nor can they handle complex relationships all in one pass. What this means is that after a pass of fixes, the changes may have caused or exposed other issues that another analysis pass will uncover. So the general usage pattern is to continue re-running analyses until "quiescence" is reached - i.e., until there are no more issues to fix. |
64 | | |
65 | | ==== Milestone Dependency Analysis ==== |
66 | | The popular [wiki:MasterTicketsPlugin master tickets plugin] enables specifying dependencies amongst tickets and visualizes them via graphviz. However, the plugin doesn't include support to manage these dependencies such as detecting when tickets are scheduled out of order. That's where this Milestone Dependency Analysis comes in. |
| 38 | == Installation and Configuration |
| 39 | |
| 40 | 1. Download and unzip the plugin. |
| 41 | 2. Install the plugin: |
| 42 | {{{#!sh |
| 43 | cd analyzeplugin/0.12 |
| 44 | sudo python setup.py bdist_egg |
| 45 | sudo cp dist/TracAnalyze*.egg /your/trac/location/plugins/ |
| 46 | }}} |
| 47 | |
| 48 | See [t:TracPlugins TracPlugins] for more installation details and options. You'll likely need to restart Trac's web server after installation. |
| 49 | |
| 50 | 3. Enable the plugin by adding the following to your `trac.ini` file: |
| 51 | {{{#!ini |
| 52 | [components] |
| 53 | analyze.* = enabled |
| 54 | }}} |
| 55 | |
| 56 | You can alternatively use the Trac Web Admin GUI to enable any or all rules. |
| 57 | |
| 58 | 4. Enable the {{{ANALYZE_VIEW}}} permission for those users who are allowed to execute analyses. |
| 59 | |
| 60 | See the examples section [wiki:AnalyzePlugin#Examples below] for how to specify rules. |
| 61 | |
| 62 | == Example |
| 63 | |
| 64 | This plugin currently includes four analyses that can each be individually enabled for one or more reports. Each analysis is configured by modifying the {{{[analyze]}}} section of {{{trac.ini}}} - see below for examples. When an analysis is enabled for a report, an '''Analyze...''' button appears at the top of the report and the analysis' name will appear in the subsequent dialog box when the button is clicked. You can either choose a single analysis or all analyses in this dialog box. Selecting "All" will run them serially. |
| 65 | |
| 66 | '''Important:''' The current analyses do not, for example, detect circular dependencies nor can they handle complex relationships all in one pass. This means that after a pass of fixes, the changes may have caused or exposed other issues that another analysis pass will uncover. So the general usage pattern is to continue re-running analyses until "quiescence" is reached, ie until there are no more issues to fix. |
| 67 | |
| 68 | ==== Milestone Dependency Analysis |
| 69 | |
| 70 | The popular [wiki:MasterTicketsPlugin master tickets plugin] enables specifying dependencies amongst tickets and visualizes them via graphviz. However, the plugin doesn't include support to manage these dependencies such as detecting when tickets are scheduled out of order. That's where this Milestone Dependency Analysis comes in: |
84 | | ==== Queue Dependency Analysis ==== |
85 | | The [wiki:QueuesPlugin queues plugin] converts one or more reports into work queues. These queues enable you to drag and drop tickets above and below one another signifying their relative priority. Each ticket's relative position is maintained in a custom field usually named {{{position}}} (but can be named anything). Dependencies amongst peer tickets in a work queue have similar problems as tickets across milestones - in this case, a dependent ticket should precede (i.e., appear higher in the queue which means have a lower {{{position}}} value), but it can be difficult to manually catch all of these dependency violations. That's where this Queue Dependency Analysis comes in. |
| 87 | ==== Queue Dependency Analysis |
| 88 | |
| 89 | The [wiki:QueuesPlugin queues plugin] converts one or more reports into work queues. These queues enable you to drag and drop tickets above and below one another signifying their relative priority. Each ticket's relative position is maintained in a custom field usually named {{{position}}} (but can be named anything). Dependencies amongst peer tickets in a work queue have similar problems as tickets across milestones - in this case, a dependent ticket should precede, ie appear higher in the queue which means have a lower {{{position}}} value, but it can be difficult to manually catch all of these dependency violations. That's where this Queue Dependency Analysis comes in: |
130 | | The {{{project_type}}} option above is the ticket type of your projects (e.g., "epic" (the default), "project", etc.). Project tickets must be of this type. |
131 | | |
132 | | The default behavior of an analysis is to refresh the current report if any fixes were made. This is so that changes can be viewed (assuming they would change the content of the report). In the case of the Project Queue Analysis, you would usually also need another report refreshed - i.e., the impacted work queue. Use the {{{refresh_report}}} option to specify this impacted work queue which will also get refreshed at the end of this analysis if there were any fixes. You can add params to the report as well if needed: |
133 | | {{{ |
134 | | #!ini |
| 131 | The {{{project_type}}} option above is the ticket type of your projects, eg "epic" (the default), "project", etc. Project tickets must be of this type. |
| 132 | |
| 133 | The default behavior of an analysis is to refresh the current report if any fixes were made. This is so that changes can be viewed (assuming they would change the content of the report. In the case of the Project Queue Analysis, you would usually also need another report refreshed - ie the impacted work queue. Use the {{{refresh_report}}} option to specify this impacted work queue which will also get refreshed at the end of this analysis if there were any fixes. You can add params to the report as well if needed: |
| 134 | {{{#!ini |
141 | | Detected problems are shown with an option to automatically fix the problem by moving the sub-task/child tickets above or below each other in their queue (to match their parent's relative positions) - see screenshot above. |
142 | | |
143 | | ==== Project Rollup Analysis ==== |
144 | | This analysis summarizes a project by "rolling up" its child tickets using one of several statistical methods. For example, you may have a report of project (or "epic" in agile-speak) tickets whose sub-tasks are represented in their {{{blockedby}}} dependencies. You would like each project ticket's fields to summarize (or roll up) those of its child tickets. That's where this Project Rollup Analysis comes in. |
| 141 | Detected problems are shown with an option to automatically fix the problem by moving the sub-task/child tickets above or below each other in their queue (to match their parent's relative positions), see screenshot above. |
| 142 | |
| 143 | ==== Project Rollup Analysis |
| 144 | |
| 145 | This analysis summarizes a project by "rolling up" its child tickets using one of several statistical methods. For example, you may have a report of project (or "epic" in agile-speak) tickets whose sub-tasks are represented in their {{{blockedby}}} dependencies. You would like each project ticket's fields to summarize (or roll up) those of its child tickets. That's where this Project Rollup Analysis comes in: |
197 | | * The core analyses are maintained in python modules that require no imports. This was intentional so that they may be easily wrapped and called from a monitoring script (e.g., [https://github.com/trifthen/NagAconda nagaconda] for nagios) so that you can be proactively alerted to ticket scheduling issues without needing to manually run analyses in Trac. |
198 | | |
199 | | == Extensibility (implementation details) == |
200 | | Each analysis is implemented as a Trac extension point to allow for new analyses to be added fairly easily. See [browser:analyzeplugin/0.12/analyze/analysis.py analysis.py] for the {{{IAnalysis}}} interface. In brief, you only need to define two methods for each analysis: |
| 197 | * The core analyses are maintained in python modules that require no imports. This was intentional so that they may be easily wrapped and called from a monitoring script, eg [https://github.com/trifthen/NagAconda nagaconda] for nagios, so that you can be proactively alerted to ticket scheduling issues without needing to manually run analyses in Trac. |
| 198 | |
| 199 | == Extensibility (implementation details) |
| 200 | |
| 201 | Each analysis is implemented as a Trac extension point to allow for new analyses to be added fairly easily. See [browser:analyzeplugin/0.12/analyze/analysis.py analysis.py] for the {{{IAnalysis}}} interface. In brief, you only need to define two methods for each analysis: |