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 or 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 additionally provide a more flexible alternative, which provides 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: tabular reports and charts showing tracked and untracked 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. 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. 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. 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 ---