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 show how that 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 simply 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 and report time spent, with low
  friction.
- Support all workflows.
- Provide an extension-friendly tool.
- Support policies, events via the rules system.
- Integrate with Taskwarrior, Tasksh.
- Store data in plain UTF-8 text files.


Non-Goals
---------
- No dependency on Taskwarrior, Taskserver and Tasksh.
- Time tracking is about recording the past, not planning the future.
- No cloud support, no sync support, all data is local. Tracked time is
  sensitive personal data and will not be transmitted.
- No explicit multi-user support, although using overlapping tags to track
  individuals will be possible.
- No features without a compelling use case.


Reports
-------
Anticipating all reporting needs is impossible, therefore custom reports are
required. Rather than only provide the Taskwarrior design where flexibility is
provided via configurable options for fixed-format reports, Timewarrior will
use a more flexible approach of providing configuration and data via an
extension API. This will not limit the kind of reports or supported formats
that can be added.

Timewarrior will ship with several extension reports, which serve as example
extensions for users to modify and improve, perhaps contribute back to the
project.

Timewarrior will also have a limited set of built-in reports, a minimally
functional tabular and chart report of tracked time.


Tags
----
Tags represent tracking categories. Tags are arbitrary UTF8 strings. A tag may
be a single unquoted word, or a quoted string if it includes spaces.

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, and an end date, when it expires. A tag may have a budget,
which is the maximum trackable time for a period.

An interval may have multiple tags associated with it, but the tags apply to the
whole interval only. In this example, there are overlapping tags:

  $ timew start tag1
  ...
  $ timew start tag2
  ...
  $ timew stop tag1
  ...
  $ timew stop

By default, when the interval for 'tag2' starts, the interval for 'tag1' is
automatically stopped, because tags do not overlap. This then makes the next
command ('timew stop tag1') yield an error, because 'tag1' was not active. If
however, both 'tag1' and 'tag2' are defined with the 'overlap' metadata, then
there will not be an automatic stop for 'tag1'.


Hints
-----
There are built-in hints, that influence processing. For example, ':debug' puts
the program in debug mode, and ':fill' indicates to a 'track' command that you
wish to fill in the available time. Another hint, ':week' means that a command
should only affect the last week.

There are user-defined hints, that can act as macros⁄aliases, for example the
':staff' hint could mean a 'Staff Meeting' and 'Admin' tag set.


Commands
--------
The command set will include:

  config         Modify configuration
  track          Record tracked time
  report         Run a report
  undo           Undo a change
  tags           Show all tags
  gaps           Show untracked gaps in the schedule
  import         Import JSON data
  export         Export JSON data
  help           Show help text
  x              Run extension 'x'

There will be built-in commands, and an extensions mechanism that allows reports
to be added as extensions, although presented and handled as though they were
built-ins.


Undo
----
All commands that change configuration or data need to be recorded as-is in the
undo.data file, so that an 'undo' command can later rewind the changes properly.

All undo will happen at the command level, not the delta level. That means if
one command results in three changes, a single 'undo' command will revert the
three changes associated with the one command.


Extensions
----------
A simple extension mechanism allows custom reports to be written and shared.
Most reports will be external scripts that use the extension API.


DOM Access
----------
Timewarrior will support a DOM, allowing rules and extensions to access internal
data.


--- Raw Notes ---

- Need syntax to adjust any recorded data.

- It should be forgiving when you forgot to stop a task. Maybe a specific
  command, instead of "stop" use "forgot" or directly "edit".  Then I would
  like to express either "stopped 30min ago" or "it lasted only 1hour”.

- Need a JSON --> CSV converter, for spreadsheet folks. Therefore csv.py could
  be an extension that converts the format.

- Use display granularity/resolution to see more or less details.  This would
  combine nicely with a tag hierarchy. (Tomas Babej)

- Need reports to help users doing fixed-rate work - finding the longest task
  for example.

- If an interval has more than one tag with a defined color, and is being
  rendered, then use the first tag color. It doesn't really matter which.