Changes between Initial Version and Version 11 of TimingAndEstimationPluginUserManual

05/31/11 12:38:54 (10 years ago)
Timing and Estimation Plugin



  • TimingAndEstimationPluginUserManual

    v1 v11  
     3= Timing and Estimation Plugin User Manual = 
     4[ TimingAndEstimationPlugin on TracHacks] | [ Open Tickets] | [ New Ticket]  |  
     5[ Web Browsable Source Code] 
     7== Abstract Design Goal == 
     8My goal in writing this plugin was to use as much of the existing structure as possible (therefore not needing to add extra structure that might make maintainability difficult).  The largest downside I have found to this is that there is no way to attach more permissions to anything. 
     10== Custom Ticket Fields == 
     11In adhering to our design goal, rather than creating a new ticket interface, I create some custom fields and a small daemon to watch over them.   
     13=== Fields: === 
     14 * '''Hours to Add''' This field functions as a time tracker.  When you add hours to it , those hours get added to the total hours field.  The person  who made the change is there fore credited with the hours spent on it. 
     15 * '''Total Hours''' This field is the total number of hours that have been added to the project. This has been made uneditable by including javascript which replaces the input box with a span containing its value 
     16   * Reports might not agree with each other if this is manually edited (which is possible if you disable javascript). 
     17 * '''Is this billable?''' An extra flag on tickets so that they can be marked as billable / not billable. 
     18 * '''Estimated Hours''' a field that contains the estimated amount of work 
     19=== Future Fields === 
     20 * '''Ticket Rate''' The ability to attach a cost per hour or total amount to an individual ticket 
     22== Management Page == 
     23This page provide a small interface for querying the tickets and adding a bill date at the current time.   
     24This interface mostly just gives you links that match the interface to open any of the give reports, 
     25providing it the correct set of input parameters 
     27The 'Management' button should be in the main title bar.  It is possible that if you are viewing at a low resolution, it was pushed off the edge of the screen.  Also if you are not logged in with report_view permissions, it will not show that button. 
     29The direct url is '/Billing'. 
     32=== Set Bill Date === 
     34This button will add now as a bill date.  This is mostly to make it 
     35easier to select the last time you billed.  This would allow you to 
     36set a ticket as having been billed at a given time while others have 
     37not, and accurately get the correct billing information for all 
     40== Reports == 
     41=== Report Types === 
     42We provide a few different reports for querying different types of data: 
     43    * '''Billing Reports''' Currently the billing reports are the only time based reports, and are therefore useful for getting an estimate what tickets had times (and totals), and which developers spent their time where. 
     44       * Ticket Work Summary 
     45       * Milestone Work Summary 
     46       * Developer Work Summary 
     47    * '''Ticket/Hour Reports''' These reports are useful for reviewing estimates on a large scale or getting an idea of the project at large.  These reports currently ignore the time. 
     48       * Ticket Hours 
     49       * Ticket Hours with Description  
     50       * Ticket Hours Grouped By Component 
     51       * Ticket Hours Grouped By Component with Description 
     52       * Ticket Hours Grouped By Milestone 
     53       * Ticket Hours Grouped By Milestone with Description 
     54=== Adding More Reports === 
     55To add reports to the Management screen sections, you must run the following sql against your trac database 
     56Remember to fill in the @reportID of the report you want to insert, and to select the insert statement for the section of your choice. 
     57 * {{{INSERT INTO custom_report (id, uuid, maingroup, subgroup, version, ordering) VALUES (@reportID , @uuid, 'Timing and Estimation Plugin', 'Billing Reports', 1, 0);}}} 
     58 * {{{INSERT INTO custom_report (id, uuid, maingroup, subgroup, version, ordering) VALUES (@reportID , @uuid, 'Timing and Estimation Plugin', 'Ticket/Hour Reports', 1, 0);}}} 
     60''NB: @uuid is a globally uninque identifier created via a tool such as {{{uuidgen}}} on Linux or various [ online tools]. It is used in this plugin to provide programatic reference to specific reports such that they can be upgraded successfully on future revisions of the plugin'' 
     62=== Removing a Report === 
     63To remove reports from the Management page, run the following query.  
     64Remember to fill in the @reportID of the report you want to modify. 
     65 * To remove for this version of the plugin (will be over written in future plugin upgrades) 
     66   * {{{UPDATE custom_report SET maingroup='x'||maingroup WHERE report = @reportID;}}} 
     67 * To remove permanently (wont be over written in future plugin upgrades) 
     68   * {{{UPDATE custom_report SET version=9999, maingroup='x'||maingroup WHERE report = @reportID;}}} 
     69''NB: The 'x' part is not important - you just need to make the column read something other than 'Timing and Estimation Plugin'.'' 
     71=== TAKE NOTE === 
     72 '''The reports can only be called from the Management Page. They will not work from the Trac View Tickets page. (Due to the custom variables that need values).''' 
     74== Future Improvements == 
     75 * [ See tickets] at the [ project trac] 
     76 * Would like to suggest a couple of interfaces to Trac project, and perhaps write an implementation for them. 
     77   * ''' ICustomTicketFieldProvider ''' This should allow a plugin to provide a custom field with the ability to add html attributes and specify at least the tag name. (hopefully with a full template) This should hopefully also allow these provided custom controls to set permissions causing them to not render or to not editable. 
     78   * ''' ICustomReportProvider ''' This allows custom reports to be provided in a way that permissions can be enforced on them.  
     79 * work with advise and feedback from the user community to make this Plugin do this job adequately