[[PageOutline(2-5,Contents,pullout)]]

= Time Tracking

Support for basic time tracking is an oft requested feature (#710), but is not implemented in Trac core. Time tracking functionality can be added to Trac however, and this page is an overview of working solutions and as a howto.

 1. wiki:PluginList#ProjectTimeManagementTicketSystemExtensions recommends to use a combination of plugins, each covering time tracking functionality.

 2. There are also other possibilities by using other plugins. So far, solutions are available and described below:
    A. through [https://trac-hacks.org/tags/timing time tracking plugins]:
       * using the [th:TracHoursPlugin] (for Trac >= 0.11)
       * using the [th:BudgetingPlugin] (for Trac >= 0.12)
       * using [https://tmetric.com TMetric time tracker] (for Trac >= 0.11)
    B. modifying (patching) Trac's source code:
       * using custom ticket fields (for Trac 0.9.x, 0.10)
       * extending the data model (for Trac 0.8)

 Note that patches are unofficial, please do not report bugs through the Trac ticket system. Instead contact the [gforum:trac-users trac users mailing list] or [mailto:steffenp@gmx.de Steffen Pingel].

== Using a Plugin (Trac >= 0.10)

The '''[th:TimingAndEstimationPlugin Timing And Estimation Plugin]''' works much the same as the Trac 0.9.x custom fields approach, except that it should be easier to install and provides more in-depth reporting. It also contains a ticket change daemon that allows you to add time and display the total. Also see the [https://trac.acceleration.net/TestForTimingAndEstimation demo version], so you can try and decide if it is right for you, as well as report bugs.

The '''[th:TracHoursPlugin TracHours plugin]''' provides a different approach to time tracking (for Trac 0.11 only). Instead of adding hours via a ticket field, separate views are available for adding and reporting hours.

The '''[th:BudgetingPlugin BudgetingPlugin]''' provides splitting the work-effort for a ticket in several smaller pieces. You can configure tasks (for example implementation, documentation, etc.) and assign users.

The '''[th:WorkLogPlugin WorkLog Plugin]''' provides the ability to 'clock in' and 'clock out' and displays which users are currently working on tickets. If either the [http://trac-hacks.org/wiki/TimingAndEstimationPlugin TimingAndEstimationPlugin] or [http://trac-hacks.org/wiki/TracHoursPlugin TracHours plugin] is being used, spent time will be recorded to a ticket when the user 'clocks out'.

The '''[th:EstimatorPlugin]''' allows you to enter upfront estimations as to how long the completion of a ticket is going to take. 

== Trac 0.9.x, 0.10 (using custom ticket fields)

A less invasive way than modifying the database as required for Trac 0.8 is to add time tracking through TracTicketsCustomFields. Custom fields are meant as an extension mechanism that allows to store additional data with tickets without changing the underlying data model. 

=== Installation

This patch requires a few steps for installation:

 * Patch Trac to provide a progress bar in the Roadmap view.
 * Modify `trac.ini` for each project to add custom fields.
 * Add a ticket query (optional).
 * Use a Subversion commit hook to log spent time (optional).

==== Patching Trac

Download and apply the [http://steffenpingel.de/files/patches/trac/ time tracking patch]:

 * Download and unzip/untar Trac (see TracDownload):
{{{#!sh
wget http://ftp.edgewall.com/pub/trac/trac-0.10.tar.gz
tar -xzvf trac-0.10.tar.gz 
}}}

 * Run patch from the created trac-0.10 directory:
{{{#!sh
cd trac-0.10
wget http://steffenpingel.de/files/patches/trac/trac-time-tracking-0.10.diff 
patch -p0 < trac-time-tracking-0.10.diff
}}} 

 * (Re)install Trac (see TracInstall):
{{{#!sh
./setup.py install
}}}

==== Modifying trac.ini

Add the following section to your `trac.ini` file in your project's configuration directory, see TracIni. This needs to be done for each project that you want to enable time tracking for:

{{{#!ini
[ticket-custom]
tt_estimated = text
tt_estimated.label = Time planned

tt_spent = text
tt_spent.label = Time spent

tt_remaining = text
tt_remaining.label = Time remaining
}}}

==== Adding the query (optional)

Open your Trac project in a web browser and go to "View Tickets" -> "New Report". You may have to grant the `REPORT_CREATE` permission first. Enter a title like "Time Tracking" and the following query:

===== SQLite

{{{#!sql
SELECT DISTINCT 
   id AS ticket,
   (CASE WHEN pl.value ISNULL THEN '' ELSE pl.value END) AS planned,
   (CASE WHEN s.value ISNULL THEN '' ELSE s.value END) AS spent,
   (CASE WHEN r.value ISNULL THEN '' ELSE r.value END) AS remaining,
   (CASE WHEN ((s.value + r.value) - pl.value) = "0.0" THEN ' ' ELSE (s.value + r.value) - pl.value END) AS accuracy,
   milestone AS customer,
   summary, component, status 
  FROM ticket t, enum p
  LEFT OUTER JOIN ticket_custom pl ON
       (t.id = pl.ticket AND pl.name = 'tt_estimated')
  LEFT OUTER JOIN ticket_custom s ON
       (t.id = s.ticket AND s.name = 'tt_spent')
  LEFT OUTER JOIN ticket_custom r ON
       (t.id = r.ticket AND r.name = 'tt_remaining')
  ORDER BY milestone
}}}

===== Using PostgreSQL with psycho

{{{#!sql
SELECT DISTINCT 
   id AS ticket,
   pl.value::interval AS planned,
   s.value::interval AS spent,
   r.value::interval AS interval,
   ((s.value::interval + r.value::interval) - pl.value::interval) AS accuracy,
   milestone AS customer, summary, component, status 
  FROM enum, ticket t
  LEFT OUTER JOIN ticket_custom pl ON
       (t.id = pl.ticket AND pl.name = 'tt_estimated')
  LEFT OUTER JOIN ticket_custom s ON
       (t.id = s.ticket AND s.name = 'tt_spent')
  LEFT OUTER JOIN ticket_custom r ON
       (t.id = r.ticket AND r.name = 'tt_remaining')
  ORDER BY milestone;
}}}

===== MYSQL

{{{#!sql
SELECT DISTINCT 
   id AS ticket,
   (CASE WHEN pl.value IS NULL THEN '' ELSE pl.value END) AS planned,
   (CASE WHEN s.value IS NULL THEN '' ELSE s.value END) AS spent,
   (CASE WHEN r.value IS NULL THEN '' ELSE r.value END) AS remaining,
   (CASE WHEN ((s.value + r.value) - pl.value) IS NULL THEN ''
         WHEN ((s.value + r.value) - pl.value) = "0.0" THEN ' ' ELSE (s.value + r.value) - pl.value END) AS accuracy,
   milestone AS customer,
   summary, component, status 
  FROM enum p, ticket t
  LEFT OUTER JOIN ticket_custom pl ON
       (t.id = pl.ticket AND pl.name = 'tt_estimated')
  LEFT OUTER JOIN ticket_custom s ON
       (t.id = s.ticket AND s.name = 'tt_spent')
  LEFT OUTER JOIN ticket_custom r ON
       (t.id = r.ticket AND r.name = 'tt_remaining')
  ORDER BY milestone
}}}

==== Using a Subversion commit hook (optional)

The {{{contrib/trac-post-commit-hook}}} script is a very convenient tool to interact with Trac's ticket system on commit. It allows to modify time tracking values and ticket state through special commit messages.

 * Copy {{{trac-post-commit-hook}}} into /usr/share/trac/contrib.
 * Create a script {{{hooks/post-commit}}} in your Subversion repository that modifies '''TRAC_ENV''' to point to your local Trac project.
 * Set the executable bit: {{{chmod 755 hooks/post-commit}}}.

{{{
REPOS="$1"
REV="$2"
LOG=`svnlook log -r $REV $REPOS`
AUTHOR=`svnlook author -r $REV $REPOS`
TRAC_ENV='/var/trac/test'

/usr/bin/python /usr/share/trac/contrib/trac-post-commit-hook \
  -p "$TRAC_ENV"  \
  -r "$REV"       \
  -u "$AUTHOR"    \
  -m "$LOG"
}}}

You can now use special keywords in your commit message to modify Trac tickets. The available commands are:

||refs #id||Adds a reference to the ticket's Changelog||
||closes #id||Closes the ticket||

The time spent and the estimated time remaining are specified in parentheses. Valid units are either hours (h) or minutes (m):

||(spent xx h)||Adds xx to time spent and decreases time remaining by xx, {{{spent}}} may be omitted.||
||(spent xx h, rem yy h)||Adds xx to time spent and sets time remaining to yy.||

See {{{contrib/trac-post-commit-hook}}} for details (after applying the patch).

'''Examples:'''

{{{#!sh
svn commit -m 'Added time tracking, refs #1 (spent 4h, rem 1h)'
}}}

This adds an entry to the Changelog of ticket #1, increases the time spent by 4 hours and sets the remaining time to 1 hour:

{{{#!sh 
svn commit -m 'Added time tracking, closes #1 (1h), refs #2 (2h, rem 30m)'
}}}

This closes ticket #1, increases the time spent by 1 hour and decreases the remaining time by 1 hour. It adds an entry to the Changelog of ticket #2, increases the time spent by 2 hours and sets the remaining time to 30 minutes.

== Screenshots

Click to enlarge.

=== Roadmap

[[Image(trac-roadmap.png,400,display:block,margin-left:auto,margin-right:auto)]] 

=== Milestone

[[Image(time-tracking-milestone.png,400,display:block,margin-left:auto,margin-right:auto)]] 

=== Ticket Report

[[Image(trac-timetracking-report.png,400,display:block,margin-left:auto,margin-right:auto)]] 

== Changelog

Patches for older version of Trac can be found at http://steffenpingel.de/files/patches/trac/. 

''[http://steffenpingel.de/files/patches/trac/trac-time-tracking-0.10.diff 0.10]'' (2006-10-28)

 * The patch has been adapted for Trac 0.10

''[http://steffenpingel.de/files/patches/trac/trac-time-tracking-0.9.6.diff 0.9.6]'' (2006-07-29)

 * The patch has been adapted for Trac 0.9.6
 * Significant enhancements to the milestone page and the post-commit-hook (please see [TimeTracking#UsingaSubversioncommithookoptional the documentation] for the new syntax) have been contributed by Magnus Sandberg:
  * The milestone page now show time tracking progress bars for "Ticket status by x"
  * The commit hook can now handle different spent/remaining values for multiple tickets
 * Tooltips have been added to the time tracking progress bars

''[http://steffenpingel.de/files/patches/trac/trac-time-tracking-0.9.5.diff 0.9.5]'' (2006-05-16)

 * The patch has been adapted for Trac 0.9.5
 * Some of the rendering related label tweaks have been removed

''[http://steffenpingel.de/files/patches/trac/trac-time-tracking-0.9.5.diff 0.9.4]'' (2006-02-20)

 * The patch has been adapted for Trac 0.9.4
 * The difference between estimated and spent + remaining time is now displayed
 * The progress bar is now displayed when spent work is less than 1 h
 * Fixes for the progress bar by Michele Franzin have been merged

''[http://steffenpingel.de/files/patches/trac/trac-time-tracking-0.9.3.diff 0.9.3]'' (2006-01-31)

 * The patch has been adapted for Trac 0.9.3
 * Patches for PostGreSQL compatibility by Fredrik Corneliusson and Matthew Good have been merged

''[http://steffenpingel.de/files/patches/trac/trac-time-tracking-0.9.2.diff 0.9.2]'' (2005-12-05)

 * The patch has been adapted for Trac 0.9.2

''[http://steffenpingel.de/files/patches/trac/trac-time-tracking-0.9.2.diff 0.9]'' (2005-11-09)

 * First release for Trac 0.9 stable branch

== Known Issues

 * I couldn't see the second milestone bars so hacked the roadmap.cs to see them ... until I realized that using units (4h instead of just 4 ...) was the problem. All working now, very nice, many thanks.

 * If your ticket doesn't have a time planned and/or time remaining set, and you spend time on a ticket, you end up with negative time values, which messes up time planning by having a net time spend of zero.

== Trac 0.8 (extending the data model)

This patch is for Trac version 0.8.

A patch has been posted to #1005 that adds two new fields to the ticket table, "Planned work" and "Actual work", that can be edited in the ticket view. It also extends the Roadmap with a progress bar that displays how much work has been done and how much remains.