= Custom Ticket Time Fields  =

This page presents information on adding a new type 'time' to the list of all currently available [wiki:TracTicketsCustomFields custom ticket fields].

== Proposed Implementation ==
=== Trac core ===
 * add 'time' to available types, inheriting most of the definition from 'text', a simple (one line) text field[[BR]]

At that point TracQuery already works as intended by providing from..to
input fields on selection of custom time fields for query.
Praise to the flexible, modularized software design of Trac developers!

 * extend ''ticket.model'', ''ticket.web_ui'', ''util.datefmt'' and ''ticket/templates/ticket.html'' to
  * allow for reading unix time stamp values from db table ''ticket_custom''
  * convert unix time stamp values to localized time string
  * parse user input and consolidate different flavors of time stamps
  * write back unix time stamp to db
  * send out properly formatted notification

=== Related Trac Plugins ===
 * [th:wiki:CustomFieldAdminPlugin CustomFieldAdminPlugin], modified version to ease the setup for new field type, private patch done
 * [th:wiki:DateFieldPlugin DateFieldPlugin] working like a charm with new time field, since it's still simple text input form field
 * [th:wiki:AnnouncerPlugin AnnouncerPlugin], modified version produces reports with pretty date/time strings, private patch done

=== Discussion ===
==== Additional code dependencies ====
Amongst the few new dependencies use of ''eGenix.com'' time string parser ''mxDateTime.Parser'' for Python is the most notable one ![2]. We need to add such a powerful tool to provide a mature parser right from the start. If handled with care, similar but incompatible classes ''datetime.datetime'' and ''mxDateTime.!DateTime'' are not much of an issue. In fact it doesn't matter at all, as long as we stick to unix time stamp format for saving times in the db for other (good) reasons as well.

==== Handling ticket changed notification ====
I plan to let the notification system handle the conversion of unix time stamp values to date/time strings on it's own. I tested with a patched version of [th:wiki:AnnouncerPlugin AnnouncerPlugin] that worked. This is a good start for the [wiki:TracDev/Proposals/Announcer proposed replacement] of current Trac Notification System by Code from [th:wiki:AnnouncerPlugin AnnouncerPlugin]. This might even make per-user preference-based date/time formatting possible in the future.

=== Status of Development ===
There is working code for all intended functions. I recognized a glitch on creation of new tickets that needs to be fixed.

Happen to have access to !SourceForge, so I choose to go there and push code into a Mercurial repository there to enable further collaboration based on a distributed VCS as per suggestion from IRC channel #trac at freenode.net: 
 http://traccustom-time.hg.sourceforge.net:8000/hgroot/traccustom-time/traccustom-time

Feedback could happen now through
 * comments to #1942,
 * edits to the discussion section of this wiki page,
 * private e-mail, or
 * commits to VCS after initial per-developer arrangement inside the Sourceforge project.

Current development is based on Trac-0.12dev_r9115, testet with Python2.5 on ''Debian GNU/Linux'' stable. However it would be great to have it in trunk soon (trac-0.12.x?).
  (cboos): that's way too old to base new development upon, especially for timestamp related development, as r9210 introduced a big change here (time are now stored as microseconds elapsed since epoch, as bigints).
    Ah, well, thanks for the hint. We're at r9420 right now, any recommendation where to start from other than HEAD? I'll have to reinstall my test platform here and re-base changes then. However starting with standard unix time seconds was easier to debug for me (i.e. comparing to date +%s). And to_timestamp() messed up the date values converted from mxDatetime for some reason. I went for the included mxDatetime.Datetime.ticks() function to get good unix time seconds. So I may still need an own function to calculate unix time microseconds from unix time seconds.
      Checked changes between r9115 and r9435, prepare for updates this weekend. Found 23 changesets that did modify files I touched by now. Sounds quite big. Try to figure out a way to do it save for now, postpone to do it clever with least effort later. Might want to use Mercurial Queues or the like, but I fell I don't understand all the consequences.

== Related tickets ==
 #710 asking for basic time tracking in Trac, especially missing native ''due_date'' and custom field type 'numeric'[[BR]]
 '''#1942 the main resource''' on requests and considerations '''related to the topic'''[[BR]]
 #1943 asking for time based calculations in queries, essentially based on #1943[[BR]]
 #1962 asking for due dates on tickets & email notification on overdue dates, several tricks and workarounds needed for using date strings the way you'd expect true time values to match, sort, etc.[[BR]]
 #2288 asked for date/time based ticket query functions, that exist by now[[BR]]
 #8354 seeking to get more date/time related information from queries, following #2288[[BR]]
 #6466 asked for higher time stamp precision introduced with microseconds for ''time'' and ''changetime'' in r9210

== External related resources ==
Ideas and Open Source code was shamelessly taken from the following places:
 ![1] [http://seehuhn.de/pages/pdate Date and Time Representation in Python] by Jochen Voss[[BR]]
 ![2] [http://www.egenix.com eGenix.com], especially see ''mxDateTime'' [http://www.egenix.com/products/python/mxBase/mxDateTime/doc/#DateTime related documentation][[BR]]
 ![3] [http://docs.python.org/library/datetime.html#module-datetime Basic date and time types] from module ''datetime'' in Python>=2.3

Needed help about Python and development tools and found it i.e. at:
 [http://docs.python.org/tutorial/index.html The Python Tutorial] - the 'official' one[[BR]]
 [http://www.tutorialspoint.com/python/index.htm Python Tutorial] - and another[[BR]]
 [http://hgbook.red-bean.com/ Mercurial: The Definitive Guide] by Bryan O'Sullivan