Timewarrior - time tracking summary

[Paul Beckingham]

Here is a summary of what Timewarrior will support so far. There are more details to be worked out (easily adjusting recorded intervals, for example). The language deliberately makes it sound like this all exists (it does not), because it will be the basis for the introductory documentation.

Feedback is appreciated, and the window for incorporating more capabilities is about to close.

Paul



Introduction
============
Timewarrior is a time tracking application, which allows you to record your
time spent on activities. At its simplest, you tell it to start and stop
tracking time:

$ timew start
...
$ timew stop

This will record a block of time as active, between the two timestamps that
were recorded when the 'start' and 'stop' commands were run.

By using tags, you can label the blocks of active time:

$ timew start Home Cleaning
...
$ timew stop

This tags the block of time with the two tags 'Home' and 'Cleaning'. The tags
allow you to identify how you spent that time, and is used by the reporting
system to summarize time.

You can also record time retroactively. If you forgot to start recording this
morning, you can do this:

$ timew start 8:30am Home Cleaning

Or if you forgot a whole activity:

$ timew track 8:00am - 8:30am Exercise
$ timew start 8:30am Home Cleaning

More sophisticated use is possible if you have defined your work week:

$ timew define workweek mon-fri
$ timew define workday start 8:30am
$ timew define workday end 1730

$ timew track yesterday Home Painting

Once the work week is recorded, vague terms like 'yesterday' can be resolved
into actual start/stop timestamps. If you define holidays, then it knows not to
track time on those days:

$ timew define holidays eng-USA

Furthermore, Timewarrior can fill in gaps. For example:

$ timew track last tuesday :fill Research

There is a :backfill and :fill hint that tells Timewarrior how to fill the time,
for example:

$ timew track yesetrday 8am - 10am Meeting
$ timew track yesterday 3pm - 17:00:00 Training
$ timew track yesterday 2pm ProjectA :backfill
$ timew track yesterday ProjectB :fill

And the 'ProjectB' tagged interval will range from 2pm - 3pm.

Tags can have their own metadata, for example you can make a tag valid for a
given time range:

$ timew define tag ProjectA end 2016-06-30
$ timew define tag ProjectA budget 400 hours total

This is managed by a rules system that can impose constraints.

To see the currently active interval:

$ timew

(not yet determined)

Reporting tracked time can be done with a simple report:

$ timew report today
$ timew report week Home
$ timew report summary last week

Some early report mockups:

http://picpaste.com/week-zWdSp3UI.png
http://picpaste.com/day-kAqffFmZ.png

Or the data can be exported in JSON:

$ timew export last month > February.json

Some or all of the reports are written using an extension mechanism, and
will be examples of how to write other reports. Report extensions can be shared
and enhanced by the community. It should be possible to implement any kind of
report using the extension mechanism.

There is an 'undo' command for reversing changes, and a 'clear' command to
free up a slot:

$ timew clear yesterday

$ timew clear 8am - 11am

You can start, stop and resume tracking:

$ timew start Training
...
$ timew stop
...
$ timew continue

There is also a rules system that can impose constraints on the data, such as
automatically shutting off tracking after 40 hours is tracked per week, warnings
about overtime, and more.

There is built-in configuration support, logging, and assorted tools to help
you enact policy.

The data will be stored as plain text, and there will a way to merge data from
multiple sources.

[Ben Boeckel]

On Tue, Mar 15, 2016 at 14:16:51 -0400, Paul Beckingham wrote:
> Once the work week is recorded, vague terms like 'yesterday' can be resolved
> into actual start/stop timestamps. If you define holidays, then it knows not to
> track time on those days:
>
> $ timew define holidays eng-USA

What standard are you using to get these? It looks like a combination of
ISO 639-2 with IETF. Why not just use the IETF one directly (en-US
here)?

https://en.wikipedia.org/wiki/Language_code

--Ben

[Paul Beckingham]

>> $ timew define holidays eng-USA
>
> What standard are you using to get these? It looks like a combination of
> ISO 639-2 with IETF.

It comes from:
ISO-639-2
ISO-3166-1 alpha-3

But “these” is not the right word. It’s just one example I wrote to get a point across it’s not a spec. I write three letter codes out of habit, because my employer has deemed 2-letter codes inadequate.

> Why not just use the IETF one directly (en-US
> here)?
>
> https://en.wikipedia.org/wiki/Language_code

I’ll be using whatever scheme holidata.net uses at the time of release.

P

[frederic....@gmail.com]

Dear Paul,

Nice summary, seems promising !

One question springs to my mind, though : how will this interact with tasks ?

More precisely :

- Do you expect to let users timetrack a particular Taskwarrior task ? If so, do you plan to allow `timew start [task_id]`, or autocompletion on task description, or else ?

- are "tags" here the same concept as in taskwarrior ? If so, why not also prepend them with the "+" character ? In fact I have the vague feeling that I would use the timew "tags" a bit the same way as the "task description" in taskwarrior, is it your intent or do you have a radically different idea in mind ?

- Will there be "projects" too ? I assume not, as in your examples "project" is a name given to tags... I have mixed feelings about that : on one hand projects and tags may seem to be overlapping (nothing prevents us from considering "projects" as tags that, for example, we decide to be mutually exclusive... It may even proove convenient to keep the possibility to loosen this rule from time to time...). On the other hand both "tags" and "projects" features are quite common in other softwares, and I suppose it might be convenient to treat those very differently in some cases. Hamster uses a convenient syntax (namely "+" for tags and "@" for projects) which makes both equally simple to use (BTW this could be a nice shortcut for "pro:" in taskwarrior, too...)

--
Frédéric

[Paul Beckingham]

> On 2016-03-21, at 07:14, frederic....@gmail.com wrote:
>
> Dear Paul,
>
> Nice summary, seems promising !

Thanks Frédéric!

> One question springs to my mind, though : how will this interact with tasks ?

I will be writing a Taskwarrior hook script that watches for “start”, “stop”, “done” and “delete” modifications, and makes an appropriate Timewarrior call. This means that Timewarrior will track active time for tasks, and take care of the annoying “oops, I left it active over the weekend” problem.

I should reiterate though that Timewarrior is completely independent from Taskwarrior, and therefore needs to support a more general set of use cases.

> More precisely :
>
> - Do you expect to let users timetrack a particular Taskwarrior task ? If so, do you plan to allow `timew start [task_id]`, or autocompletion on task description, or else ?

I intend to provide a hook script, with decent defaults that will track all tasks. It will probably look for, and obey a ‘+notrack’ tag. My current notes say that it should send UUID, description, project, tags and one or more configured UDA attributes as Timewarrior tags.

As a hook script, it will be easily modified to customize that list, and it’s behavior. Over the longer term, I expect such hook scripts to evolve and multiply, because hooks scripts are simple programs, thus making it easy for folks to get creative.

> - are "tags" here the same concept as in taskwarrior ? If so, why not also prepend them with the "+" character ? In fact I have the vague feeling that I would use the timew "tags" a bit the same way as the "task description" in taskwarrior, is it your intent or do you have a radically different idea in mind ?

The tags will be more generalized, for example these are all valid Timewarrior tags:

123
ProjectA
‘Home & Garden’
‘Answer Frédéric\’s questions on the mailing list'

Because Timewarrior only deals with tags, there is no need for the ‘+’, but maybe for the sake of consistency it should use it. I think I’ll wait until it is functional before making that decision - there’s no substitute for actually using a program in order to discover it’s pros and cons. I hope you’ll provide feedback then.

Meanwhile, there is an issue tracker now on https://bug.tasktools.org for Timewarrior, to capture feature requests and bugs.


> - Will there be "projects" too ? I assume not, as in your examples "project" is a name given to tags... I have mixed feelings about that : on one hand projects and tags may seem to be overlapping (nothing prevents us from considering "projects" as tags that, for example, we decide to be mutually exclusive... It may even proove convenient to keep the possibility to loosen this rule from time to time...). On the other hand both "tags" and "projects" features are quite common in other softwares, and I suppose it might be convenient to treat those very differently in some cases. Hamster uses a convenient syntax (namely "+" for tags and "@" for projects) which makes both equally simple to use (BTW this could be a nice shortcut for "pro:" in taskwarrior, too…)

No projects, just tags. It might be that there needs to be some kind of hierarchical category like project, but I would prefer not, if possible.

You’re right, some of this may need to be revisited. It’s not easy trying to come up with a complete project, because with zero users there is no feedback. It’s much easier to start with a solid but lightweight framework, then carefully iterate forwards, once there are users with opinions.

The Hamster approach of using ‘+’ and ‘@‘ is a nice policy, and something that can be informally used here also, provided those are both part of valid tags, which they should be.

I like the idea of using ‘@foo’ in taskwarrior as syntactic sugar for ‘pro:foo’. But there is a problem here: ‘@‘ is used as ‘context’ in some software. I think generally it’s not a great idea to hunt for unused characters on a keyboard an

If projects are to be included, then I would expect only projects to be included, and not for this to be a long process of adding “just one more attribute", which describes Taskwarrior's history. Using Taskwarrior as a lesson, it would have been good if I had implemented UDAs from the very beginning, and only promoted UDAs to core attributes when proven to be valuable. I think Timewarrior can learn from this. So everything will initially be a tag.

P

[frederic....@gmail.com]

Dear Paul,

Just to let you know : I cloned https://git.tasktools.org/scm/tm/timew.git and I think some files are missing in src/libshared (directory is currently empty, cmake expects files there...). Of course this is a very early dev stage so maybe it is too soon (and/or I don't know how to deal with cmake properly)...

Also, I don't think the issues at https://bug.tasktools.org/browse/TI/?selectedTab=com.atlassian.jira.jira-projects-plugin:issues-panel are open to external users (at least I don't have permission to create one).

Best,

--
Frédéric

[Paul Beckingham]

Hi Frédéric,

The ‘src/libshared’ directory is a git submodule, and this means that you need this:

git clone --recursive https://git.tasktools.org/scm/tm/timew.git

The ‘--recursive’ option clones any submodules. You can also repair your current clone, but I don’t know the command. Something like ‘git submodule update’, not sure, because I haven’t tried it.

You’re right about it being early stage development, but timew can already track time crudely using ‘start’, ‘stop’ and ‘export’ commands, and there is an early Taskwarrior hook that integrates it. I don’t recommend using all this yet, but if you’re curious, then please do, and I’d appreciate feedback.

The implementation so far is mostly program structure, but it’s beginning to take shape. It’s a week or two away from being useful. But if you look in the ‘docs’ directory, you’ll find the planning and decisions and questions that are driving all this, and some of those came from you.

Regarding the issue tracking, it should be open to new submissions, and I just added a test issue. Please try that again, I don’t see any restrictions on the db or your user.

P

> --
> You received this message because you are subscribed to the Google Groups "taskwarrior-user" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to taskwarrior-us...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

[Frédéric Meynadier]

Thanks ! I was not familiar with git submodules, sorry...

For issues : I haven't tried to add a new one but the panel now looks like other projects' panel, instead of the warning I had... So it looks good !

​

[shawn wilson]

On Apr 8, 2016 9:36 AM, "Frédéric Meynadier" <frederic....@gmail.com> wrote:
>
> Thanks ! I was not familiar with git submodules, sorry...
>

Probably an autogen.sh should do that (and autoreconf -i or however the configure process for cmake goes)

Note there's also some new split feature in git that you could use instead of submodules.