revisited the task management document, based on practical experiences

2 files changed, 32 insertions, 9 deletions

diff --git a/TASK_MANAGEMENT.md b/TASK_MANAGEMENT.md
index d5c2e30..326c73b 100644
--- a/TASK_MANAGEMENT.md
+++ b/TASK_MANAGEMENT.md
@@ -91,14 +91,39 @@ Based on my interpretation of the standards, I've implemented logic in calendar-
 
 There is no support for rrules outside the task completion code, so as for now the rrule has to be put in through another caldav client tool, through the --pdb option or through manually editing ical code.  I believe recurring tasks is an important functionality, so I will implement better support for this at some point.
 
-dtstart vs due vs duration
---------------------------
+dtstart vs due vs duration vs priority
+--------------------------------------
 
 I my opinion, dtstart is the earliest time you expect to start working with the vtodo, or maybe the earliest time it's possible to start.  Passing the dtstart doesn't mean you need to drop everything else and start working on the task immediately.  You'd want to postpone the dtstart just to unclutter the todo-list.
 
-Due is the time/date when the task has to be completed, come hell or high water.  It should probably not be postponed.  Due dates should probably be set very far in the future or not set at all.  You really don't want the list of tasks that are soon due or even overdue to be cluttered up with stuff that can be procrastinated even further.
+Due is the time/date when the task has to be completed, come hell or high water.  It should probably not be postponed.  Due dates should probably be set very far in the future if no specific due date is set.  You really don't want the list of tasks that are soon due or even overdue to be cluttered up with stuff that can be procrastinated even further.
 
 Different task list implementations may behave differently, most of them is probably only concerned with the due date.
 
-According to the RFC, either due or duration should be given, never both of them.  A dtstart and a duration should be considered as equivalent with a dtstart and a due date (where due = dtstart + duration).  I find that a bit sad, I'd like to use dtstart as the time I expect to start working with a task, duration as the time I expect to actually use on the task, and due as the date when the task really should be completed.
+According to the RFC, either due or duration should be given, never both of them.  A dtstart and a duration should be considered as equivalent with a dtstart and a due date (where due = dtstart + duration).  I find that a bit sad, I'd like to use dtstart as the time I expect to start working with a task, duration as the time I expect to actually use on the task, and due as the date when the task really should be completed.  Calendar-cli does not support the duration field as of today.
 
+Sometimes one gets overwhelmed, maybe one gets a week or two behind the schedule due to external circumstances.  calendar-cli supports operations like "add one week to all tasks that haven't been done yet".  As of 2015 the default due date was one week in the future.  It has been changed to one year in the future.  Probably the best practice is to keep the due date unset unless the task has a hard due date.
+
+It's also possible to set a priority field.
+
+The default sorting is:
+
+* overdue tasks at the very top.
+* tasks that have passed dtstart above tasks that haven't passed dtstart
+* within each group, sort by due-date
+* if equal due-date, sort by dtstart
+* if equal due-date and dtstart, sort by priority
+
+My usage pattern so far:
+
+* Skip using the priority field.
+* Try to handle or postpone or delete tasks that are overdue immediately, we shouldn't have any overdue tasks (oups, this didn't work out very well, as the default due date was 7 days in the future).
+* On a daily basis, go through all uncategorized tasks.  All tasks should have at least one category set.  I typically do this while sitting on the metro in the morning.
+* On a daily basis, look through all tasks that have passed the dtstart timestamp.  I'm considering when/how to do those tasks and (re)consider what is most urgent.  It's important to keep this list short (or it gets unwieldy, demotivating, etc), so I procrastinate everything I know I won't get done during the next few days.  I move the dtstart  timestamp to some future date - depending on my capacity, the importance of the tasks, etc, I add either some few days, weeks, months or years to it.
+* Whenever I think of something that needs to be done, I add it on the task list, immediately, from the telephone.
+* I've been using the timestamps to try to prioritize the tasks.
+* Whenever I'm at some specific location or doing some specific work, I'll filter the task list by category.
+
+I believe my approach of using timestamps rather than the priority field makes some sense; by looking through the "task list for this week" on a daily basis, and adding some weeks to those I know I won't be able to do anytime soon, the task list is always being circulated, there are no tasks that really gets forgotten.
+
+Task lists tend to always grow, at some point it's important to realize ... "Those tasks are just not important enough ... I'll probably never get done with those tasks", and simply delete them.
diff --git a/calendar-cli.py b/calendar-cli.py
index 6f2bf50..cd6a2ec 100755
--- a/calendar-cli.py
+++ b/calendar-cli.py
@@ -352,8 +352,6 @@ def todo_add(caldav_conn, args):
     cal.add('prodid', '-//{author_short}//{product}//{language}'.format(author_short=__author_short__, product=__product__, language=args.language))
     cal.add('version', '2.0')
     todo = Todo()
-    ## TODO: what does the cryptic comment here really mean, and why was the dtstamp commented out?  dtstamp is required according to the RFC.
-    ## TODO: (cryptic old comment:) not really correct, and it breaks i.e. with google calendar
     todo.add('dtstamp', _now())
 
     for setarg in ('due', 'dtstart'):
@@ -585,7 +583,7 @@ def todo_list(caldav_conn, args):
             t = {'instance': task}
             t['dtstart'] = task.instance.vtodo.dtstart.value if hasattr(task.instance.vtodo,'dtstart') else date.today()
             t['dtstart_passed_mark'] = '!' if _force_datetime(t['dtstart'], args) <= _now() else ' '
-            t['due'] = task.instance.vtodo.due.value if hasattr(task.instance.vtodo,'due') else date.today()+timedelta(365)
+            t['due'] = task.instance.vtodo.due.value if hasattr(task.instance.vtodo,'due') else date.today()+timedelta(args.default_due)
             t['due_passed_mark'] = '!' if _force_datetime(t['due'], args) < _now() else ' '
             for timeattr in ('dtstart', 'due'):
                 t[timeattr] = t[timeattr].strftime(args.timestamp_format)
@@ -763,7 +761,7 @@ def main():
     todo_subparsers = todo_parser.add_subparsers(title='tasks subcommand')
     todo_add_parser = todo_subparsers.add_parser('add')
     todo_add_parser.add_argument('summaryline', nargs='+')
-    todo_add_parser.add_argument('--set-due', default=date.today()+timedelta(7))
+    todo_add_parser.add_argument('--set-due', default=date.today()+timedelta(365))
     todo_add_parser.add_argument('--set-dtstart', default=date.today()+timedelta(1))
     todo_add_parser.add_argument('--is-child', help="the new task is a child-task of the selected task(s)", action='store_true')
     for attr in vtodo_txt_one + vtodo_txt_many:
@@ -777,7 +775,7 @@ def main():
     
     todo_list_parser = todo_subparsers.add_parser('list')
     todo_list_parser.add_argument('--todo-template', help="Template for printing out the event", default="{dtstart}{dtstart_passed_mark} {due}{due_passed_mark} {summary}")
-    todo_list_parser.add_argument('--default-due', help="Default number of days from a task is submitted until it's considered due", default=14)
+    todo_list_parser.add_argument('--default-due', help="Default number of days from a task is submitted until it's considered due", type=int, default=365)
     todo_list_parser.add_argument('--list-categories', help="Instead of listing the todo-items, list the unique categories used", action='store_true')
     todo_list_parser.add_argument('--timestamp-format', help="strftime-style format string for the output timestamps", default="%F (%a)")
     todo_list_parser.set_defaults(func=todo_list)