mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-06-26 10:54:28 +02:00
126 lines
4.3 KiB
Text
126 lines
4.3 KiB
Text
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. An interval
|
||
may have any number of tags.
|
||
|
||
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, and so on.
|
||
|
||
Tags may be deifned as overlapping, which allows the tracking of multiple
|
||
simultaneous intervals. By default, tags do not overlap.
|
||
|
||
|
||
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
|
||
--------
|
||
There is a set of built-in commands that allow all the functionality to be
|
||
used. An extension mechanism allows arbitrary read-only commands to be added.
|
||
Extensions will be seamlessly integrated.
|
||
|
||
|
||
Extensions
|
||
----------
|
||
A simple extension mechanism allows custom reports to be written and shared.
|
||
Most reports will be external scripts that use the extension API.
|
||
|
||
|
||
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.
|
||
|
||
|
||
Rules
|
||
-----
|
||
Rules are configuration-based settings and logic. Rules will be able to define
|
||
conditions and actions, thus implementing policies.
|
||
|
||
|
||
DOM Access
|
||
----------
|
||
Timewarrior will support a DOM, allowing rules and extensions to access internal
|
||
data.
|
||
|
||
|
||
Roadmap
|
||
-------
|
||
Timewarrior will not initially implement all the above features. A roadmap lays
|
||
out the plan for getting to a full-featured release.
|
||
|
||
ihttp://taskwarrior.org/docs/design/plans.html
|
||
|
||
|
||
--- Raw Notes ---
|
||
|