Changes between Initial Version and Version 14 of TimingAndEstimationPluginUserManual


Ignore:
Timestamp:
Jul 9, 2010, 2:54:55 PM (7 years ago)
Author:
Timing and Estimation Plugin
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • TimingAndEstimationPluginUserManual

    v1 v14  
     1
     2
     3[[PageOutline]]
     4= Timing and Estimation Plugin User Manual =
     5[http://trac-hacks.org/wiki/TimingAndEstimationPlugin TimingAndEstimationPlugin on TracHacks] | [http://trac-hacks.org/report/9?COMPONENT=TimingAndEstimationPlugin Open Tickets] | [http://trac-hacks.org/newticket?component=TimingAndEstimationPlugin&owner=bobbysmith007 New Ticket]  |
     6[http://trac-hacks.org/browser/timingandestimationplugin/trunk Web Browsable Source Code]
     7
     8== Abstract Design Goal ==
     9My 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
     11== Custom Ticket Fields ==
     12In 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
     14=== Fields: ===
     15 * '''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.
     16 * '''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
     17   * Reports might not agree with each other if this is manually edited (which is possible if you disable javascript).
     18 * '''Is this billable?''' An extra flag on tickets so that they can be marked as billable / not billable.
     19 * '''Estimated Hours''' a field that contains the estimated amount of work
     20=== Future Fields ===
     21 * '''Ticket Rate''' The ability to attach a cost per hour or total amount to an individual ticket
     22
     23== Billing / Management Page / Time Reports ==
     24This page provide a small interface for querying the tickets and adding a bill date at the current time. 
     25This interface mostly just gives you links that match the interface to open any of the give reports,
     26providing it the correct set of input parameters
     27
     28The direct url is '/Billing'.
     29
     30=== No Permissions Branch ===
     31The '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.
     32
     33=== Permissions Branch ===
     34The 'Time Reports' button should be in the main title bar.  Whether or not you see this will be based on whether your user has TIME_VIEW permissions.
     35
     36
     37
     38
     39=== Set Bill Date ===
     40
     41This button will add now as a bill date.  This is mostly to make it
     42easier to select the last time you billed.  This would allow you to
     43set a ticket as having been billed at a given time while others have
     44not, and accurately get the correct billing information for all
     45tickets.
     46
     47== Reports ==
     48=== Report Types ===
     49We provide a few different reports for querying different types of data:
     50    * '''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.
     51       * Ticket Work Summary
     52       * Milestone Work Summary
     53       * Developer Work Summary
     54    * '''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.
     55       * Ticket Hours
     56       * Ticket Hours with Description
     57       * Ticket Hours Grouped By Component
     58       * Ticket Hours Grouped By Component with Description
     59       * Ticket Hours Grouped By Milestone
     60       * Ticket Hours Grouped By Milestone with Description
     61=== Adding More Reports ===
     62To add reports to the Management screen sections, you must run the following sql against your trac database
     63Remember to fill in the @reportID of the report you want to insert, and to select the insert statement for the section of your choice.
     64 * {{{INSERT INTO custom_report (id, uuid, maingroup, subgroup, version, ordering) VALUES (@reportID , @uuid, 'Timing and Estimation Plugin', 'Billing Reports', 1, 0);}}}
     65 * {{{INSERT INTO custom_report (id, uuid, maingroup, subgroup, version, ordering) VALUES (@reportID , @uuid, 'Timing and Estimation Plugin', 'Ticket/Hour Reports', 1, 0);}}}
     66
     67''NB: @uuid is a globally uninque identifier created via a tool such as {{{uuidgen}}} on Linux or various [http://www.famkruithof.net/uuid/uuidgen 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''
     68
     69=== Removing a Report ===
     70To remove reports from the Management page, run the following query.
     71Remember to fill in the @reportID of the report you want to modify.
     72 * To remove for this version of the plugin (will be over written in future plugin upgrades)
     73   * {{{UPDATE custom_report SET maingroup='x'||maingroup WHERE report = @reportID;}}}
     74 * To remove permanently (wont be over written in future plugin upgrades)
     75   * {{{UPDATE custom_report SET version=9999, maingroup='x'||maingroup WHERE report = @reportID;}}}
     76''NB: The 'x' part is not important - you just need to make the column read something other than 'Timing and Estimation Plugin'.''
     77
     78=== TAKE NOTE ===
     79 '''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).'''
     80
     81== Permissions Branch ==
     82Recently a branch of this plugin was sponsored by [http://www.obsidiansoft.com/ Obsidian Software] so that it would support per field permissions. 
     83
     84This is accomplished with Genshi 5 stream filters in trac 11.  This code draws from the [http://trac-hacks.org/wiki/BlackMagicTicketTweaksPlugin BlackMagicTicketTweaksPlugin]
     85{{{
     86#!html
     87<br />
     88<a href="http://www.obsidiansoft.com/" >
     89<img src="http://trac-hacks.org/attachment/wiki/TimeEstimationUserManual/obsidian-logo.gif?format=raw" />
     90</a>
     91}}}
     92
     93=== Configuration ===
     94There is a new trac.ini configuration section which is filled in by default as follows.
     95{{{
     96#!ini
     97[field settings] # per field permissions
     98
     99# a list of all the fields to apply permissions to
     100fields = billable, totalhours, hours, estimatedhours, internal
     101
     102# a bunch of:
     103# field.permission = PERMISSION:consequence
     104#
     105#  If PERMISSION=ALWAYS, then the consequence always occurs
     106#    eg: billable.permission = ALWAYS:hide
     107#        will always result in billable being hidden, irrespective of user permissions   
     108#
     109# where consequence is one of: hide, remove, disable
     110#    hide - replaces with hidden input
     111#    remove - removes element
     112#    disable - removes input in favor of text
     113billable.permission = TIME_VIEW:hide, TIME_RECORD:disable
     114totalhours.permission = TIME_VIEW:remove, TIME_RECORD:disable
     115hours.permission = TIME_RECORD:remove
     116estimatedhours.permission = TIME_RECORD:disable
     117internal.permission = TIME_RECORD:hide
     118}}}
     119
     120It also adds an "Internal" checkbox which allows you to set a ticket as internal.  For this policy to work correctly you need to add a line to the trac section of the config telling it which permission policies to use.  (The setup will attempt to put this line of configuration in place. )  The permission that looks at currently is 'TIME_ADMIN'.  To change that group set the internalgroup of the ticket section in the trac.ini as follows:
     121
     122{{{
     123#!ini
     124[ticket]
     125internalgroup = TRAC_ADMIN #or whatever group / permission you want
     126
     127[trac]
     128permission_policies = InternalTicketsPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy
     129}}}
     130
     131== Future Improvements ==
     132 * [http://trac-hacks.org/report/9?COMPONENT=TimingAndEstimationPlugin See tickets] at the [http://trac-hacks.org/wiki/TimingAndEstimationPlugin project trac]
     133