File: design.txt

package info (click to toggle)
gnotime 2.3.1~snapshot20091119-1
  • links: PTS, VCS
  • area: main
  • in suites: squeeze
  • size: 5,348 kB
  • ctags: 1,515
  • sloc: ansic: 15,043; sh: 3,857; xml: 1,367; makefile: 237; lisp: 138
file content (134 lines) | stat: -rw-r--r-- 5,447 bytes parent folder | download | duplicates (6)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

Design Quickie Overview
-----------------------
by Linas Vepstas, January 2003


Overall Structure
-----------------
GTT is, today, a fairly small, simple application.  It is big enough to
have a handful of semi-independent components, but small enough that it
is manageable by one developer.

GTT four basic parts:
1) the 'engine', a set of C objects that encapsulate 
   project, task and time interval data with a set of 
   GUI-independent programming API's.  The API is in proj.h,
   the code in proj.c and the private data structs in 
   proj_p.h.  The goal of splitting out the data this way is
   to make it easier to write an SQL back-end for storage,
   and/or to interface to the web via cgi-bins.
   
2) some code to read/write the structs to an XML-formatted
   file. The code in in xml-read.c, xml-write.c

3) The 'journal' code.  This code displays the diary
   of project activity as html, inside the gtkhtml html
   widget.  It uses scheme as an extension language, so 
   that the user can design custom forms.  The code is in
   ghtml.c.  The design should be sufficiently abstract
   that it could be piped to anything (e.g. to cgi-bins
   in apache).

4) The Gnome GUI.  This is most of the rest of the files,
   including the parts of the GUI done up with glade.


Projects, Sub-projects, Tasks and Intervals
-------------------------------------------
An 'interval' is supposed to just be a record of a timer start & stop
and not much more.  (see, however, 'interval fuzz' below).

A 'task' is supposed to be just a text memo associated with some
intervals.  Think of a task as a kind of a "diary entry": a place
where you can write down what you did today.   You can't go back
and restart old tasks because you can't go back and re-live yesterday.
(Tasks are mis-named, and should probably have been called 'diary 
entries').

If you want to 'restart' a task, then what you should really do is to
set up a set of sub-projects.  Projects & sub-projects can always be
restarted: that is what a sub-projects are supposed to be. 


All About Billing
-----------------
There are four supported billing rates: regular, overtime,
double-overtime and flat-rate.  The dollar values for these are stored
in the project structure.   Which of these to use is an enum associated
with a task.   'flat_rate' is what it sounds like: the amount to bill
for the task, independent of the actual time spent.

Tasks can also be classed as billable or not in four ways:
billable -- go ahead an bill for this.
free of charge -- print on invoice but price is zero
not billable -- do not print on invoice.
hold -- potentially billable, but still being edited for correctness.

Tasks have a bill unit: everything on the bill will appear as a 
multiple of this value.  Typically 15 minutes or an hour.  Interval
totals less than this are rounded up to a bill unit.


Interval Fuzz
-------------
If users need to hand-enter ex-post-facto hours into gtt, they may not 
exactly remember the exact start time, down to the exact second.  
Their memory is fuzzy.  The interval 'fuzz' is used to indicate
how uncertain the start time is.  Typically, its 0, 300, 900 or 3600
seconds.  If set to 12*3600, it just means "I did this work sometime
today", but is otherwise vague about when.  (So, for example, in this
case, the start time should be understood to indicate a day, but not
a time.)

Just because the fuzz is set doesn't mean that the interval is
inaccurate.  Its still assumed that the interval is correct down to the
last second.  


Notes vs. Memos:
----------------
Memo's are meant to be printed on invoices, whereas notes are meant to
be kept internal, not shown to the customer.


Custid
------
Customer id.   Not used at the moment, future hook for customer
name/address/vcard,etc. info for invoicing.

Automatic Backup
----------------
Code in main.c performs automatic backup of the data files.

It saves once a minute for the first 4 minutes, then once every 4 
minutes for the first 16 minutes, then once every 16 minutes for 
the first 64 minutes, etc., forever.  There is nothing to adjust,
there is nothing to configure, and the old copies are pruned 
automatically.  Because of the logarithmic distribution, it means that
even if you run for years, you won't have more than 20 or so backup 
copies (viz. every 4 months for the first 16 months, etc).

The algorithm seems safe: the code never actually deletes files,
it only renames them: The pruning works by copying a newer file on top
of an older file.  Thus, even if the app goes totally wacko, it can't
wack much: there's no chance of an 'rm *' happening by accident.


Future Plans
------------
GTT is as much an application as an experimental platform for application
development.  I would like to explore the following with GTT:

-- Make the interface highly user-configurable.  There are many application
   development frameworks that try to provide this but none are defacto
   market leaders, and none offer the right mix between domain ontology
   (the stuff that should be 'hard cocded') and what should be user
   configurable.

   One thing I want to explore is how to build and integrate an 'application
   designer' into gtt.  The point being that a highly-configurable app
   requires a rather complex preferences dialog.  This should be split
   off as a stand-alone application, so that naive users aren't bothered
   by it, but power users can make use of it.