timewarrior/doc/project.txt

Timewarrior Project
===================
Timewarrior is a program that records tagged time blocks that represent tracked
time. This data is then used to create reports that shwo how time was spent.

To make this task easier, and more useful, Timewarrior can access holidays, a
pre-defined working schedule, and support flexible time/date specifications,
implement a simple stop-watch tracking feature, generate custom reports, and
apply a set of rules to impose constraints and check the data.

Using a hook scripts, Timewarrior can be used as a backend time-tracking
feature for Taskwarrior, any other program, or as a standalone utility.

Timewarrior aims to be the tool of choice if you need to track time and generate
timesheets.


Goals
-----
Provide a personal tool to easily track time spent and generate reports in
multiple formats and styles. The tool will "do the right thing" as much as
possible, to make detailed time tracking easy, and low friction.

Data will be stored as plain UTF8 text.

Open Source.


Non-Goals
---------
- No cloud support, no sync support, all data is local. Tracked time is
  sensitive personal data and wll not be transmitted.
- No explicit multi-user support, although using tags to track individuals is
  possible.
- No precision higher than a minute.


Tags
----
Tags represent tracking categories. Tags are arbitrary UTF8 strings. A tag may
be a single unquoted word, or a quoted phrase.

A tag may be used without being defined, but if a tag is defined, then it may
have associated metadata, such as a start date representing the first date on
which it may be used, or an end date, when it expires. A tag may have a budget,
which is the maximum trackable time for a period.


Macros
------
A macro is a keyword that can take arguments, and expands to a set of one or
more other timew commands, with some dynamic aspect. For example, the macro
named 'staff meeting' could be an interval that is on Wednesdays at 10:00, and
has a set of associated tags. This would then create an appropriately tagged
interval.


Commands
--------
The command set may include:

  define         Modify configuration
  track          Record tracked time
  report         Run a report
  tags           Show all tags
  query          Extract an interval set
  import         Import JSON data
  export         Export JSON data
  x              Run extension 'x'


Extensions
----------
A simple extension mechanism would require an executable script found in a
defined location with a conformant name, which then is fed queried raw data as
stdin.

For example, this script clearly defines that it is a 'report' extension named
'abc'.

  ~/.timewarrior/extensions/report_abc

---

- Need Terminology for backwards and forwards tracking (backfill for the past, and just assume everything else is for the future)?

- Given this:
    $ timew track yesterday 9am - 5pm tag1
  What does this do:
    $ timew track yesterday 10am - 11am tag2
  Does it yield:
    a) yesterday 540-1020 tag, 600-660 tag2                      # overlap
    b) yesterday 540-600 tag1, 600-660 tag2, 660-1020 tag1       # no overlap
    c) yesterday 540-600 tag1, 600-660 tag1 tag2, 660-1020 tag1  # explicit overlap
  Stating 'track yesterday 10am - 11am tag2' sounds imperative, thus overriding any existing tags in that interval. Perhaps a 'merge' keyword could be added to combined the results (track yesterday 10am - 11am tag2 merge)?

- Need an undo feature.

- Need a log file, controlled by a logging rule.

- start (frontfill) and backfill (end) could be considered orthogonal to each other. They just operate into different directions. but I think they behave the same, more or less.

- Intervals for different tags may overlap. We multitask.

- Need syntax to adjust any unarchived recorded data.

P: There is no open-ended fill though.  The future is infinite, so we don’t want to actually record much.  Anything bounded, yes (“until eod”), but anything unbounded (“track ‘do this’”) just leaves it open.
F: it fills from the last good point, goes backwards in time until it hits a stop/interval limit.
P: Yes, unless you bound it.  ie   “timew track last week ‘this thing’” can back fill within the “last week”, but exclude any otherwise tracked intervals.
   Then we can support a “merge” keyword to overlap any tracked intervals.
F: If you add fill to this I would expect it to start at the end of last week, find the empty intervall and fill it until it hits a limit or another already filled interval.
   So it only does one thing.
   while the command without fill would operate on the entire week instead.
   but this would just be me.
P: Let’s explore that.  Suppose “last week” is 39 hours of nothing, and 1 hour of a meeting.  Suppose we indicate (for clarity here) keywords as “:keyword”.  The question then becomes what do the following do:
   $ timew track last week “paint the thing”
   $ timew track last week “paint the thing” :fill
   Our choices are:
   39 hours of “paint the thing” filled around the 1 hour “meeting”.
   Or 40 hours of “paint the thing” overlapping with 1 hour “meeting”
   Or 40 hours of “paint the thing”, and the meeting is gone
F: hm, b would be first choice.
   “a" would be second or third.

F: I think we could generally use it to “fill” around other already tracked events.
P: So a normal human only does one thing at a time.
F: Yes but then also to make a difference between this
   say you had this:
   timew track 9-10 meeting
   so now a noon you realise that you don’t have anything tracked for 8-9 and 10-12.
   If I then do timew track 8 "reading email” it either stops automatic tracking for email at 9 (or continues and erases meeting - whatever if that makes sence).
   but with timew track 8 “reading email” fill it would do 8-9 mail and 10-12 mail around the 9-10 meeting.
   I think it would be more logic to stop a tracking of an event if a new event comes along.
P: I like that:  “timew track 8 read” fills in 8-9 and stops.  “timew track 8 read :fill” fills in 8-9, 10-12.
F: Yes.
F: Perhaps this could be used in the same way for the yesterday example... So the double tracking would not occur.
P: Agreed.
F: Only when doing it explicitly.
P: There is a use-case for double tracking.  Suppose I am a manager, and I do this:
   $ timew track yesterday “paint the door” fredde
   $ timew track yesterday “paint the window” paul
   It’s a valid use case.  So there would be some kind of configuration that says “this tag can overlap with that tag, but not itself”.
t  I thought of this: Using a tag with pre-defining it is what we have discussed so far.
   But if a tag is predefined somehow (timew define tag “…”) then it could live in configuration, and have metadata, such as an expiration date.  This corresponds to “you can’t bill this client after EOM”.
   It could have a start date, which means “cannot bill before next month”.
   Could also define overlap.  This could be implemented using Rules.