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 tags to track individuals is possible. - No features without a compelling use case. Reports ------- Anticipating all reporting needs is impossible, therefore custom reports are required. Rather than copy 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 reports, which serve as example extensions for users to modify and improve, perhaps contribute back to the project. Purely as an example of what might be implemented, here are some report mockups: ./report.week.txt ./report.day.1.txt ./report.exc.week.txt 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, while being 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.