"U" to show/set/clear urgency coefficients

linuxcaffe commented 9 years ago

Urgency co-efficients are one of the things that make taskwarrior unique. It's a a powerful feature that lets users assign a co-efficient to many different attributes, and it drives the order of the "next" report, among other things. The function was introduced many years ago (after some badgerring by me) and has been extended and enhanced since then. Current values can be seen using 'task show ...' and as calculated, in the 'task info' report.

However, imho, the feature has not yet reached the point where it can actually be (easily) used as intended. The central idea is that by setting co-efficient values, that match your own ideas of urgency, the "next" and ready" reports will naturally be sorted by the things that are most important to you. Technically, this is possible, but practically, to set a coefficient requires editing a .taskrc configuration line for each coefficient, and the going back and forth to the "ready" report, to see how this has been calculated. This is cumbersome, at best, and I believe that users are not getting the benefits that a finely-tuned set of coefficients could provide. I have been thinking about this problem for years, trying to imagine by what means a decent set of co-efficient values could be set up, and I have come to the conclusion that vitw is the only tool that could make this process tolerable.

Here's how I imagine it could work:

Firstly, co-efficients can only be applied to certain fields, and an attempt to set an UrgCo for anything else (like a description) should simply fail with an error message. Here's the big list of possible settings, from 'man taskrc;

The urgency calculation uses a polynomial with several terms, 
each of which has a configurable coefficient. Those coefficients are:
       urgency.next.coefficient=15.0
              Urgency coefficient for 'next' special tag
       urgency.blocking.coefficient=8.0
              Urgency coefficient for blocking tasks
       urgency.blocked.coefficient=-5.0
              Urgency coefficient for blocked tasks
       urgency.inherit.coefficient=0.0
              Urgency inherited from dependency chain
       urgency.due.coefficient=12.0
              Urgency coefficient for due dates
       urgency.priority.coefficient=6.0
              Urgency coefficient for priorities
       urgency.waiting.coefficient=-3.0
              Urgency coefficient for waiting status
       urgency.active.coefficient=4.0
              Urgency coefficient for active tasks
       urgency.scheduled.coefficient=5.0
              Urgency coefficient for scheduled tasks
       urgency.project.coefficient=1.0
              Urgency coefficient for projects
       urgency.tags.coefficient=1.0
              Urgency coefficient for tags
       urgency.annotations.coefficient=1.0
              Urgency coefficient for annotations
       urgency.age.coefficient=2.0
              Urgency coefficient for the age of tasks
       urgency.age.max=365
              Maximum age in days. After this number of days has elapsed, 
the urgency of a task won't increase any more because of aging.
       urgency.user.tag..coefficient=...
              Specific tag coefficient.
       urgency.user.project..coefficient=...
              Specific project coefficient.
       urgency.uda..coefficient=...
              Presence/absence of UDA data.
       urgency.uda...coefficient=...
              Specific value of UDA data.
       The  coefficients  reflect the relative importance of the various terms in 
the urgency calculation. These are default values, and may be modified to suit 
your preferences, but it is important that you carefully consider any modifications.

Many of these settings apply to the presence of an attribute (due, priority, waiting, active, scheduled,project, tags, age, uda.< name >) and to set those values, hitting "U" while over a corresponding field-heading, should bring up a prompt;

 
Urgency coefficient:

(prepopulated with existing value, if any) to show/set/clear those coefficients.

For those UrgCo that apply to specific user-values (user.tag, user.project, uda.< name >.< value >) hitting "U" while over a corresponding cel, containing such a value, would bring up the "Urgency coefficient:" prompt, to be applied to those user-values. If a user tried to invoke "U" while over a blank field, or a field with no associated UrgCo setting, they would get a "invalid selection" error message. It would also be illogical to try and set a coefficient In the case of multiple tags, so this would only work on a tag field with a single tag..

I am imagining that with this function enabled, and using it while looking at the "ready" report, a user could immediately see the effect, tasks rising or falling in the sort order, after each change, and with a relatively quick UrgCo-setting session, could tweak the values to match their own real-world urgency. Without this vitw function, I fear that the taskwarrior concept of fine-grained urgency, will never really be realized, and usable only for a few rude sort overrides.

This function, unlike all the others. would directly manipulate values in .taskrc. It's not the simplest feature-request, but it is the only way I can imagine to effecively set taskwarrior coefficients.

linuxcaffe commented 9 years ago

to be even clearer about the field or user-value in focus, maybe the prompt should not be just "Urgency coefficient:" but the rc name of the coefficient. For eample, it the cursor were in the headings row over the Project field, hitting "U" would result in;

urgency.project.coefficient: 1.0

and if over a user-generated tag "baz", hitting "U" would prompt:

urgency.user.tag.baz.coefficient:

blindFS commented 9 years ago

I have implemented the basic functions.

Some questions:

How to treat those values with spaces. for example what if the project name is "foo bar" ?
Is there a better way to get all uda fields?

linuxcaffe commented 9 years ago

YAY!

ehem.. ok then..

values with spaces should be treated as a single item, project:'foo bar'
a terse list of udas can be generated with helper-command "_udas"

linuxcaffe commented 9 years ago

I've had a chance to start playing with the new feature (and thank you so much for implementing it) so here's some feedback;

1) after changing an urgency value, while looking at the ready report (which is sorted by urgency) I should see an immediate change in the sort order, and I'm not seeing it. What is meant by ":TWEditTaskrc to checkout"? Is that just to see the change?

2) When the cursor is in the header (top) row, and "U" is invoked, the coefficient for the presence of a value should change, For example, over Project should change " urgency.project.coefficient" (this is working) BUT when the cursor is over a specific project value (below the header row) then the coefficient for the user-value should be changed, for example, over project "foo", invoking "U" should produce prompt " urgency.user.project.foo.coefficient:". This should also apply to tag "bar" (urgency.user.tag.bar.coefficient:) and uda "baz" (urgency.uda.example.baz.coefficient:)

linuxcaffe commented 9 years ago

In attempting to change the urgency for a field or value, for which there is no associated coefficient (eg, over ID, Description or Urg) nothing happens. It would be better to see an error like "invalid selection". The error message should also be seen when attempting to change the coefficient of a multiple-tag field, as it doesn't make sense to try and change the urgency.user.tag.___.coefficient of multiple tags.

linuxcaffe commented 9 years ago

Not all columns are visible in all reports, but in the interest of feature completeness, these column-headings should be associated with their coefficients;

start = urgency.active.coefficient entry = urgency.age.coefficient depends = urgency.blocked.coefficient parent = urgency.blocking.coefficient waiting = urgency.waiting.coefficient

linuxcaffe commented 9 years ago

.. in other words, the only logical place to set 'due', 'priority', 'project', 'tags', 'age', 'scheduled', 'uda' (implemented) 'active', 'age', 'blocked','blocking', 'waiting' (yet to be implemented) coefficients, is the top, field-headings row.

Below the headings row, the only valid selections shoud be

a project (urgency.user.project.foo.coefficient)
a single tag (urgency.user.tag.foo.coefficient)
a uda value (urgency.uda.bar.baz.coefficient)

which leaves only three possible coefficients unexposed;

any entry (age) value (urgency.age.max)
any depends (blocked) value, or indicator (D) (urgency.inherit.coefficient)
any annotation (urgency.annotations.coefficient)

That's it! That's every possible urgency coefficient logically exposed!

invoking "U" should result in an error (something like "invalid selection") for any of the following;

cursor over a blank cell
a cell with multiple tags
below the header row in any 'active', 'blocking', 'due', 'priority', 'scheduled', or 'waiting' column
anywhere in a 'description' column, except over an annotation.
anywhere in any 'end', 'id', 'imask', 'mask', modified', 'recur', 'status', 'until' or 'uuid' column

Future versions of taskwarrior may feature new urgency coefficients,,but until then, with the additions and exceptions above, all available coefficients could be shown/set/cleared by vim-taskwarrior.

blindFS commented 9 years ago

I mean what's the option for project "foo bar" ? Apparently not urgency.user.project.foo bar.coefficient neither urgency.user.project.'foo bar'.coefficient, ...project.foo-bar...., project.foo_bar...., so currently it will fallback to urgency.project.coefficient.

And if the position doesn't make any sense, it will just sort the tasks according to urgency. For multiple tags, it will choose the <cword> tag if possible, otherwise fallback to urgency.tags.coefficient.

linuxcaffe commented 9 years ago

That may be a task bug/oversight. I'll see what the tw devs have to say about that over IRC. as to urgency.tags.coefficient and urgency.project.coefficient, imho, they should anly be settable from the header row, as they apply to all values in the field. Perhaps the conditions you illustrated above should just throw an error?

blindFS commented 9 years ago

I think it will be nicer to always have a fallback behavior. For example, a field with empty value, fallback to the same behavior of the corresponding head, nonsense field fallback to just sorting tasks by urgency. ab9422db8bf4c9726044e79ff46d7a6b2e451e9c works this way

linuxcaffe commented 9 years ago

I just tried that fresh code, and it still doesn't seem possible to show/set/clear urgency.user values.. am I missing something?

blindFS commented 9 years ago

What will happen when you press U on a project column with value of just 1 word?

linuxcaffe commented 9 years ago

urgency.user.project.word.coefficient ? (if over a project named "word") urgency.project.coefficient (if over the Project field-heading)

blindFS commented 9 years ago

It should be.

linuxcaffe commented 9 years ago

doesn't seem to be..

blindFS commented 9 years ago

What's the output of echo taskwarrior#data#get_value_by_column(line('.'), 'project')? with the cursor on it? Maybe some German characters? I made it only for [0-9A-Za-z], I'll fix it if I find out which special characters should be taken care of, for example '[ %$#]'.

linuxcaffe commented 9 years ago

in vim :echo taskwarrior#data#get_value_by_column(line('.'), 'project') results in:

Error detected while processing function taskwarrior#data#get_value_by_column..taskwarrior#data#get_uuid..taskwarrior#data#get_value_by_column:
line    5:
E121: Undefined variable: b:task_report_columns
E116: Invalid arguments for function match(b:task_report_columns, '^'.a:column.'.*')
E15: Invalid expression: match(b:task_report_columns, '^'.a:column.'.*')
line    6:
E121: Undefined variable: b:task_report_columns
E116: Invalid arguments for function index(b:task_report_columns, a:column))
E116: Invalid arguments for function taskwarrior#data#get_value_by_index(a:line, index(b:task_report_columns, a:column))
E15: Invalid expression: taskwarrior#data#get_value_by_index(a:line, index(b:task_report_columns, a:column))
line    5:
E121: Undefined variable: b:task_report_columns
E116: Invalid arguments for function match(b:task_report_columns, '^'.a:column.'.*')
E15: Invalid expression: match(b:task_report_columns, '^'.a:column.'.*')
line    6:
E121: Undefined variable: b:task_report_columns
E116: Invalid arguments for function index(b:task_report_columns, a:column))
E116: Invalid arguments for function taskwarrior#data#get_value_by_index(a:line, index(b:task_report_columns, a:column))
E15: Invalid expression: taskwarrior#data#get_value_by_index(a:line, index(b:task_report_columns, a:column))

linuxcaffe commented 9 years ago

I'm not sure it's related, but I have noticed some dysfunction lately with "m" modify; the existing values are no longer pre-populated, and therefore it's easy to accidentally clear out a value using "m". If it persists I'll file a proper bug issue.

linuxcaffe commented 9 years ago

oops! I followed the above test instructions badly, did the ":echo..." in vim, but not over a vitw project. Attempts to do it within a vitw report give NO results.. I'm doing it wrong ;-)

blindFS commented 9 years ago

I can't reproduce the problem, but I've changed the implementation of that function in 036bbb2cec3b27a72990755edf9490232e6f6eed . If you still have a problem, maybe you could show me your taskrc.

linuxcaffe commented 9 years ago

(problem solved!)

small complaint: after setting an urgency coefficient, and moving the cursor, the prompt and value-just-changed doesn't go away. It would be better if the prompt disappeared after moving the cursor, or hitting ESC.

linuxcaffe commented 9 years ago

Projects can have implied hierarchies like project:top.sub.sub, but attempting to set the urgency of such a project fails (falls back to urgency.project.coefficient) When task evaluates the urgency of such a task, it does so only on the first (top level) of the project, the part before the first "." and so vitw should see proj:one.two.three, and "U" should only apply urgency.user.project.one.coefficient, ignoring the "two.three" part

blindFS / vim-taskwarrior

"U" to show/set/clear urgency coefficients #106