Use Cases ========= This document contains a set of use cases and expected behavior. This will gradually change into a feature spec. The use cases are grouped functionally: [1] Basic Usage [2] Reports [3] Exclusions [4] Tags [5] Fill [6] Configuration [1.1] Basic Usage: clock ------------------------ Using the 'start' and 'stop' commands without tags just records time intervals: $ timew start ... $ timew stop This results in a recorded interval with the 'default' tag. [1.2] Basic Usage: clock + tags ------------------------------- Using the 'start' and 'stop' commands with tags just records time intervals: $ timew start tag1 ... $ timew start tag2 ... $ timew stop This results in the 'tag1' interval being automatically stopped, and the new 'tag2' interval starting. The 'stop' command stops all tracking. As these tags are not defined, there is no additional metadata. [1.3] Basic Usage: no arguments ------------------------------- Simply running the command with no arguments will show any currently tracking interval, with associated tags: $ timew 2016-02-29 8:00:00 - now, 3:11:24 total, using 'tag1' If 'tag1' has a defined color, it is used here to color the 'tag1' string. [2.1] Reports: Summaries ------------------------ There are several time-based default reports which summaries tracked time over preset periods: $ timew report day $ timew report week $ timew report month $ timew report quarter $ timew report year $ timew report [3.1] Exclusions: Work Week -------------------------- $ timew define holidays eng-USA $ timew define holidays work 2015-11-26 $ timew define workweek mon-fri $ timew define workday start 8:30am $ timew define workday end 1730 $ timew define workday tue end 3pm [5.1] Fill: Backfill -------------------- If the time is 12:13pm, the workday starts at 8:00am, and you have already tracked a 9am-10am meeting, then this command will automatically backfill the 8am-9am interval only: $ timew track 8am "Reading email" Similarly, this command will do the same thing: $ timew track 8:23am "Reading email" :backfill These two examples assume that there is no empty slot at the end of yesterday, because it would also be filled. Backfill involves looking backwards from the stated date/time, looking for an interval to define the start. Only when a range is bounded can :fill and :backfill determine the interval. [5.2] Fill: Fill (forwards) --------------------------- If a time range is bounded, then :fill can determine an end point, and fill the gap. For example: $ timew track today tag1 The 'today' is a bounded range, and this command will use 'tag1' for an interval that extends all day today. Similarly 'tomorrow', 'next week' are bounded. [5.3] Fill: Autofill -------------------- By using tags, this becomes: $ timew start tag1 # Start tracking now $ timew start "Home Improvement Project" # Stop old interval, start new interval now $ timew stop # Stop all tracking $ timew report month # Run report 'month' If a time is specified, it always means today: $ timew track 8am - 10am tag1 If days are specified, they always mean the past: $ timew track mon - wed tag1 If today is thursday, the following covers the curent week because the previous monday would be after the previous friday, therefore the friday refers to the next friday, at EOW: $ timew track mon - fri tag1 If overlapping intervals are permitted (configuration: interval.overlap=yes), then this creates overlapping intervals: 1 $ timew start tag1 ... 2 $ timew start tag2 ... 3 $ timew stop tag1 ... 4 $ timew stop tag2 With overlapping intervals: o-------o tag1 o--------o tag2 1--2----3---4---> time Track time but backfill to the most recent interval end: $ timew track :backfill tag1 Record yesterday's time: $ timew track yesterday tag1 The above examples simply use ad-hoc tags, which is an undefined tag. They are simply used as tags, and have no metadata. Defining a tag allows it to have associated metadata: $ timew define tag "tag1" $ timew define tag "tag1" description "Description of tag1" $ timew define tag "tag1" start 2016-01-01 $ timew define tag "tag1" end 2016-06-30 $ timew define tag "tag1" budget 20 hours per week $ timew define tag "tag1" budget 400 hours total $ timew define tag "tag1" overlap --- - Need to break all these out into separate sections, where each is discussed in sufficient detail to then generate user docs and code. - Need to differentiate ":fill", ":backfill" and automatic fill. - Outline case for double-tracking, perhaps where a manager tracks the time of several employees. This would require that tracked time for a single tag has no overlaps, but allowing overlapping intervals might need configuration to allow this. - Do we need arbitrary exclusions? Lunch? Dentist Appointment? or are those just different inclusions? - Suppose "last week" is 39 hours of nothing, and 1 hour of a meeting. The question becomes what do the following do: [1] $ timew track last week "paint the thing" [2] $ timew track last week "paint the thing" :fill Our choices are: [a] 39 hours of "paint the thing" filled around the 1 hour "meeting". [b] 40 hours of "paint the thing" overlapping with 1 hour "meeting" [c] 40 hours of "paint the thing", and the meeting is gone Consensus: [b], but configurable. - Given this scenario: Exclusion: ------| Exclusion: |---------- Inclusion: |-| Now: | Timeline: >--o---o---o---o---o---o---o---o---o---o---o---o---o--> 7 8 9 10 11 12 1 2 3 4 5 6 7 am pm $ timew track this morning :fill tag inc 8am - 9am # tag $ timew track this morning :fill :active tag inc 8am - 9am # tag inc 9:30am - # tag $ timew track today tag inc 8am - 9am # tag inc 9:30am - # tag $ timew track 8am - 9am tag inc 8am - 9am # tag $ timew start tag1 :fill inc 9:30am - # tag