Changes between Version 41 and Version 42 of AnalyzePlugin


Ignore:
Timestamp:
Oct 16, 2016, 7:00:51 AM (5 years ago)
Author:
figaro
Comment:

Further cosmetic changes

Legend:

Unmodified
Added
Removed
Modified
  • AnalyzePlugin

    v41 v42  
    11[[PageOutline(2-5,Contents,pullout)]]
    22
    3 = Analyzes tickets for dependency and other problems
     3= Analyze tickets for dependency and other problems
    44
    55== Description
     
    6262== Example
    6363
    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.
     64This 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.
    6565
    6666'''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.
     
    6868==== Milestone Dependency Analysis
    6969
    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:
     70The 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:
    7171
    7272[[Image(issue-milestone.png, border=2)]]
     
    7575
    7676 * {{{blockedby}}} tickets are ''peer'' ordering relationships
    77  * {{{blockedby}}} tickets are ''project (aka parent-child) relationships'' - where the parent/project's milestone is the latest milestone for the work to be completed
     77 * {{{blockedby}}} tickets are ''project (aka parent-child) relationships'', where the parent/project's milestone is the latest milestone for the work to be completed
    7878
    7979To enable this analysis for a given report, list those reports in {{{trac.ini}}} as follows:
     
    8383}}}
    8484
    85 Detected problems are shown with an option to automatically fix the problem by moving tickets into appropriate milestones - see screenshot above.
     85Detected problems are shown with an option to automatically fix the problem by moving tickets into appropriate milestones, see screenshot above.
    8686
    8787==== Queue Dependency Analysis
    8888
    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:
     89The [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:
    9090
    9191[[Image(issue-queue.png, border=2)]]
     
    104104}}}
    105105
    106 In this example, report 2 uses both {{{queue}}} and {{{milestone}}} fields to define a queue whereas report 9 uses only the {{{queue}}} field.  You may also specify additional filters to skip tickets with certain field values (pipe-delimited):
     106In this example, report 2 uses both {{{queue}}} and {{{milestone}}} fields to define a queue whereas report 9 uses only the {{{queue}}} field. You may also specify additional filters to skip tickets with certain field values (pipe-delimited):
    107107{{{#!ini
    108108[analyze]
     
    110110}}}
    111111
    112 In this example, the {{{queue}}} field defines the queue in report 9 and the analysis will skip any ticket in this queue with {{{type}}} equal to "epic" or {{{phase}}} equal to "verifying" or "releasing".  These would typically match the {{{WHERE}}} clause in the report's SQL.
     112In this example, the {{{queue}}} field defines the queue in report 9 and the analysis will skip any ticket in this queue with {{{type}}} equal to "epic" or {{{phase}}} equal to "verifying" or "releasing". These would typically match the {{{WHERE}}} clause in the report's SQL.
    113113
    114114Detected problems are shown with an option to automatically fix the problem by moving tickets above or below each other in the queue - see screenshot above.
     
    131131The {{{project_type}}} option above is the ticket type of your projects, eg "epic" (the default), "project", etc. Project tickets must be of this type.
    132132
    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:
     133The 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 parameters to the report as well if needed:
    134134{{{#!ini
    135135[analyze]
     
    153153}}}
    154154
    155 In the example above, this analysis is available for reports 1, 2, 3, and 9.  If no {{{rollup_reports}}} is provided, then the {{{project_reports}}} list is used instead.
     155In the example above, this analysis is available for reports 1, 2, 3, and 9. If no {{{rollup_reports}}} is provided, then the {{{project_reports}}} list is used instead.
    156156
    157157The available rollup stats are:
     
    195195 [[TicketQuery(blocking~=1234,format=table,col=position|id|summary|severity|owner|effort|milestone|phase,order=position,group=type)]]
    196196 }}}
    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.
     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.
    198198
    199199== Extensibility (implementation details)
     
    204204 * {{{get_solutions(self, db, args)}}} - return a dict of {{{name}}} and {{{data}}} fields, or a list of these, that each define a solution option for how to fix the detected issue.
    205205
    206 where {{{args}}} are the request args and {{{data}}} is any serializable (to JSON) python object that contains all of the data needed to automatically fix the problem. If this {{{data}}} object is a dict of ticket fields and their new values (or a list of these), then the default {{{fix_issue()}}} method will automatically apply the fix upon user command. If your fix is more involved, you can override this method:
     206where {{{args}}} are the request args and {{{data}}} is any serializable (to JSON) Python object that contains all of the data needed to automatically fix the problem. If this {{{data}}} object is a dict of ticket fields and their new values (or a list of these), then the default {{{fix_issue()}}} method will automatically apply the fix upon user command. If your fix is more involved, you can override this method:
    207207
    208208 * {{{fix_issue(self, db, data, author)}}} - fix the issue using the data that was returned earlier from {{{get_solutions()}}}.