[[PageOutline(2-5,Contents,pullout)]] = [wiki:TracHoursPlugin TracHours] User Manual == Introduction The TracHoursPlugin is designed to help track time that is spent working on Trac tickets. This tutorial explains how to use this plugin. After installing and enabling the TracHoursPlugin, you should be able to see its functionality by going to the '''Hours''' tab on the nav bar: [[Image(nav.png, border=2)]] [wiki:TracHoursPlugin TracHours] introduces new screens, at `/hours` (the query view) and `/hours/` (the hours view for that ticket). [wiki:TracHoursPlugin TracHours] also modifies the ticket screen to display estimated and total hours (see below) and the roadmap view to compute the hours (if the `TracHoursRoadmapFilter` component is enabled): [[Image(milestone.png, border=2)]] == Adding Hours to a Ticket [wiki:TracHoursPlugin TracHours] adds two custom fields to tickets: `Estimated Hours` and `Total Hours`. `Estimated Hours` can be updated as a typical custom field, though only numerical values are accepted. `Total Hours` is a computed field and cannot be updated from the ticket page. When you make a new ticket, `Total Hours` will be `0`. [[Image(newticket.png, border=2)]] For an existing ticket, the `Total Hours` field will be a link to the [wiki:TracHoursPlugin TracHours] screen for that ticket: [[Image(ticket.png, border=2)]] As an example for ticket 1, this will link to `/hours/1`. Going to this screen will allow you to verbosely see, add to, and edit the hours for a ticket: [[Image(ticket_hours.png, border=2)]] If you have `TRAC_ADMIN` permission (as shown), you can add and edit hours for any user. Otherwise you will only be able to add and edit hours as yourself if you have the `TICKET_ADD_HOURS` permission). If you are not logged in, you can view hours but not add them. You can also edit existing hours from this screen (only your own, unless you're a `TRAC_ADMIN`). If you add hours with a description, the addition will be logged to the ticket comments and appropriate notifications will be sent. == Viewing Hours for Several Tickets Clicking on the Hours tab in the navigation bar or going to `/hours` gives a screen where the hours for all tickets can be queried and tallied. The `/hours` screen is designed to mimic the Trac [/query custom query] screen in terms of look and feel, except that what is being queried over are hours addition events and not tickets. The hours (both estimated and tracked) are totaled above the ticket query results. [[Image(query_hours.png, border=2)]] By default, hours accrued in the last week are shown with a convenience link to the previous week. Like the Trac [/query custom query], filters may be added over ticket reporter, owner, and other fields. == Additional Ways of Adding Hours In addition to the view at `/hours/`, additional components provide other ways of adding hours: === Adding Hours with the Ticket Sidebar The [source:trachoursplugin/0.11/trachours/web_ui.py TracHoursSidebarProvider] component adds a sidebar for on existing tickets for convenient posting of hours: [[Image(TracHoursPlugin:hours-ticket-sidebar.png, border=2)]] The TicketSidebarProviderPlugin will additionally have to be installed and enabled for the sidebar element to appear. It will also only show up if you have the `TICKET_ADD_HOURS` permission. When adding hours via the sidebar, they will be logged as the currently authenticated user at the time that the form is submitted. Comments will not be made. === Adding Hours via Comments The [source:trachoursplguin/0.11/trachours/ticket.py TracHoursByComment] component allows addition of hours by commenting on a ticket. Comments containing snippets like `5 hours`, `1 hour`, `3.7 hours`, or `0:30 hours` will be recorded for the ticket when the comment is submitted if the commenter has the `TICKET_ADD_HOURS` permission (otherwise, they will go unrecorded). The comments will also be logged to !TracHours' database and may be viewed additionally in `/hours/`, which should be linked to by the comment. In addition to being able to log hours by comments through the web, `TracHoursByComments` also plays nicely with other methods of annotating tickets: * hours may be added via replies to ticket emails using the MailToTracPlugin. Make sure that you have `TracHoursByComment` in your `[mail]` handlers for the link to be properly marked up: {{{#!ini [mail] handlers = RemoveQuotes, TracHoursByComment, ReplyToTicket, EmailToTicket }}} * hours may be added via an svn post-commit hook, at least the one in RepositoryHookSystemPlugin. Make sure you include a ticket reference: {{{#!sh svn ci -m 'add footnote, took 2 hours ; refs #6' }}}