Improving dt's UI

[David Wolever]

As I lay in bed, my mind was racing with thoughts of building the
ideal issue tracking software... It would be entirely filesystem
based, a command line wrapper to make things easier, it would support
all sorts of searching...
Now imagine my disappointment when I found out that it was already
implemented!

Anyway, after some playing around with dt, it seems to do exactly
what I want... With one small exception: I've found the UI to be very
"clunky". I'm not a huge fan of all the prompts -- I'd much rather
be put in $EDITOR. For example:
- The 'add' command forces you to pick a version, and there is no way
to set a default (breaking train of thought)
- There is no clear way, in one "action", to close an issue and
include a commit message
- There is no clear way to "just add something (comment, header, etc)
to a ticket"

It seems to me like it would be a lot easier to be given $EDITOR with
the appropriate headers for any given action (ie, a `dt close` would
add the "DT-New-Status: closed" header for you), then after $EDITOR
is closed, check that everything is there, prompting (with a default,
so enter can be mashed) for any missing values.

So, the question is: is there any technical reason not to do this?
And, next question, if I was to do it, would that make people happy?

Thanks,
David

[Vlad Skvortsov]

Post by David Wolever
As I lay in bed, my mind was racing with thoughts of building the
ideal issue tracking software... It would be entirely filesystem
based, a command line wrapper to make things easier, it would support
all sorts of searching...
Now imagine my disappointment when I found out that it was already
implemented!

Oh, I'm sorry for your disappointment! :-)

Post by David Wolever
Anyway, after some playing around with dt, it seems to do exactly
what I want... With one small exception: I've found the UI to be very
"clunky". I'm not a huge fan of all the prompts -- I'd much rather
- The 'add' command forces you to pick a version, and there is no way
to set a default (breaking train of thought)

Hmm, we just never had such a requirement, but it seems to be trivial to
implement. It needs to be configurable though.

Post by David Wolever
- There is no clear way, in one "action", to close an issue and
include a commit message

Just use 'c' and 'e' commands in the same session. Or, for
non-interactive use, dt act $ISSUE -a close:fixed -m "Your commit message".

Post by David Wolever
- There is no clear way to "just add something (comment, header, etc)
to a ticket"

Again, just invoke 'dt act' and then use 'e' or 'h' commands
respectively. Or, dt act $ISSUE -m "Some comment"; dt act $ISSUE -a
change-header:header=value.

Post by David Wolever
It seems to me like it would be a lot easier to be given $EDITOR with
the appropriate headers for any given action (ie, a `dt close` would
add the "DT-New-Status: closed" header for you), then after $EDITOR
is closed, check that everything is there, prompting (with a default,
so enter can be mashed) for any missing values.

Hmm, currently -m or -F options are mandatory if -a is supplied to
'act'. We could make them optional, and if they are omitted, drop into
$EDITOR with "preset" headers. Would it work for you?

Post by David Wolever
So, the question is: is there any technical reason not to do this?
And, next question, if I was to do it, would that make people happy?

Patches are always welcome. :-) We just to make sure that the whole
workflow is consistent after adding new features.

[David Wolever]

Post by Vlad Skvortsov

Post by David Wolever
Anyway, after some playing around with dt, it seems to do exactly
what I want... With one small exception: I've found the UI to be very
"clunky". I'm not a huge fan of all the prompts -- I'd much rather
- The 'add' command forces you to pick a version, and there is no way
to set a default (breaking train of thought)

Hmm, we just never had such a requirement, but it seems to be
trivial to
implement. It needs to be configurable though.

Ok, sounds good. When I get into work today I'll tinker with it it a
bit and see what I can do about a patch.

Post by Vlad Skvortsov

Post by David Wolever
- There is no clear way, in one "action", to close an issue and
include a commit message

Just use 'c' and 'e' commands in the same session. Or, for
non-interactive use, dt act $ISSUE -a close:fixed -m "Your commit message".

Post by David Wolever
- There is no clear way to "just add something (comment, header, etc)
to a ticket"

Again, just invoke 'dt act' and then use 'e' or 'h' commands
respectively. Or, dt act $ISSUE -m "Some comment"; dt act $ISSUE -a
change-header:header=value.

Clearly I need to brush up on my RTFMing skills...
While that is much easier than I thought it was, I still (at least in
theory) don't like the two steps -- it strikes me as a common use-
case that should be simpler...
But, of course, I don't _actually_ know what I'm talking about
because I haven't used dt for any amount of time yet... So I'll keep
my mouth shut until I've got some evidence or a patch :P

Post by Vlad Skvortsov

Post by David Wolever
It seems to me like it would be a lot easier to be given $EDITOR with
the appropriate headers for any given action (ie, a `dt close` would
add the "DT-New-Status: closed" header for you), then after $EDITOR
is closed, check that everything is there, prompting (with a default,
so enter can be mashed) for any missing values.

Hmm, currently -m or -F options are mandatory if -a is supplied to
'act'. We could make them optional, and if they are omitted, drop into
$EDITOR with "preset" headers. Would it work for you?

That wouldn't be bad, but is there any reason not to just add another
command?

Post by Vlad Skvortsov

Post by David Wolever
So, the question is: is there any technical reason not to do this?
And, next question, if I was to do it, would that make people happy?

Patches are always welcome. :-) We just to make sure that the whole
workflow is consistent after adding new features.

Wonderful :)
Hopefully I'll have some diffs to review shortly.

[Vlad Skvortsov]

Post by David Wolever

Post by Vlad Skvortsov

Post by David Wolever
- The 'add' command forces you to pick a version, and there is no way
to set a default (breaking train of thought)

Hmm, we just never had such a requirement, but it seems to be trivial to
implement. It needs to be configurable though.

Ok, sounds good. When I get into work today I'll tinker with it it a
bit and see what I can do about a patch.

...so, am I understanding you correctly that you'd like to skip the
version selection menu altogether if there is only one version in the
"present" set? What if there are more than one?

I'm talking about the current dt UI (not about that you are proposing
below).

Post by David Wolever

Post by Vlad Skvortsov

Post by David Wolever
- There is no clear way to "just add something (comment, header, etc)
to a ticket"

Again, just invoke 'dt act' and then use 'e' or 'h' commands
respectively. Or, dt act $ISSUE -m "Some comment"; dt act $ISSUE -a
change-header:header=value.

Clearly I need to brush up on my RTFMing skills...
While that is much easier than I thought it was, I still (at least in
theory) don't like the two steps -- it strikes me as a common use-case
that should be simpler...

And by "two steps" you mean that you have to invoke dt twice? Actually,
it's possible to do both actions with a single invocation of dt:

dt act $ISSUE -m "Some comment" -a change-header:header=value

Post by David Wolever

Post by Vlad Skvortsov

Post by David Wolever
It seems to me like it would be a lot easier to be given $EDITOR with
the appropriate headers for any given action (ie, a `dt close` would
add the "DT-New-Status: closed" header for you), then after $EDITOR
is closed, check that everything is there, prompting (with a default,
so enter can be mashed) for any missing values.

Hmm, currently -m or -F options are mandatory if -a is supplied to
'act'. We could make them optional, and if they are omitted, drop into
$EDITOR with "preset" headers. Would it work for you?

After a second thought I think it's not a great idea: -a, -m and -F are
used for non-interactive work, so people used to that (myself included)
would find it surprising that an editor pops up when they (mistakenly)
omitted, say, -m.

Post by David Wolever
That wouldn't be bad, but is there any reason not to just add another
command?

I would prefer to keep the number of commands to minimum, especially if
there are ways to achieve the desired result using the existing ones. By
the way, if your preference is to have a separate command for each
logical action, this can be achieved by shell aliases.

As for the "drop me to an editor" functionality you mentioned, let me
first take a look at your patch to better understand what you are
looking for.

[David Wolever]

Post by Vlad Skvortsov

Post by David Wolever
Ok, sounds good. When I get into work today I'll tinker with it
it a bit and see what I can do about a patch.

...so, am I understanding you correctly that you'd like to skip the
version selection menu altogether if there is only one version in
the "present" set? What if there are more than one? I'm talking
about the current dt UI (not about that you are proposing below).

I would like to skip as much interaction as possible, while still
ensuring that all the required fields (category, version, etc) still
exist.
Now that I've got a patch, just take a look at that and see how it
does the defaults and such :)

Post by Vlad Skvortsov

Post by David Wolever
Clearly I need to brush up on my RTFMing skills...
While that is much easier than I thought it was, I still (at least
in theory) don't like the two steps -- it strikes me as a common
use-case that should be simpler...

And by "two steps" you mean that you have to invoke dt twice?
Actually, it's possible to do both actions with a single invocation
dt act $ISSUE -m "Some comment" -a change-header:header=value

Ah, so it is.

Post by Vlad Skvortsov

Post by David Wolever
... 'act'. We could make them optional, and if they are omitted,
drop into
$EDITOR with "preset" headers. Would it work for you?

After a second thought I think it's not a great idea: -a, -m and -F
are used for non-interactive work, so people used to that (myself
included) would find it surprising that an editor pops up when they
(mistakenly) omitted, say, -m.

Good point. Breaking muscle memory is defiantly a bad thing.

Post by Vlad Skvortsov

Post by David Wolever
That wouldn't be bad, but is there any reason not to just add
another command?

I would prefer to keep the number of commands to minimum,
especially if there are ways to achieve the desired result using
the existing ones. By the way, if your preference is to have a
separate command for each logical action, this can be achieved by
shell aliases.

I agree that it's a good idea to keep the number of commands down
(*glares at git*), but I think there is a benefit to making common
actions built in commands (even if some sort of internal code just
expands them as aliases).
There are three reasons for this:
0) Shell aliases don't work everywhere (eg, when I use `:!...` from
Vim, aliases don't work)
1) They aren't standard -- when I go to my friend's machine, he
doesn't have my aliases, so he either has to type a lot more (using
the internal commands) or duplicate my aliases.
2) It's not very standard to require long commands for common
actions. For example, adding, moving, removing and copying are all
separate commands in svn -- it doesn't use something like `svn shell
--command=mv` (the exception, of course, is `propset`, but it's got
`propedit` too, so it's not TOO bad)

BUT, you're probably much smarter than I am, and you've defiantly
been using DI much longer than I have, so what I'm saying may be
entirely true, but completely irrelevant in this case.

Post by Vlad Skvortsov
As for the "drop me to an editor" functionality you mentioned, let
me first take a look at your patch to better understand what you
are looking for.

Ok, sounds good. In my mind, it would be identical to my new
implementation of `add`, just accepting a ticket number as as an
argument (in fact, now that I think about it, they could probably use
most of the same code too...)

[David Wolever]

I suppose it can be made without removing our current functionality.
We should just add new level of abstraction "choosing version from a
list". And have two implementation of that new level, choosing the
needed one from configuration.
...
Also i propose to use some sort of comment in $EDITOR.
For example, you could get the following, when running ./dt new
Added-by: gli
Category: dt/dt -- dt/dt, dt/ui, dt/tools
Reported-for: 0.3 -- 0.3, 0.4, 0.5
Due-in: 0.4 -- 0.3, 0.4, 0.5

Ah, nice, I like that interface even better than the X-Default...
headers I had.

...
David, do i correctly understand your proposition?

Yup, Ivan, I think you've got it exactly.

The only thing that strikes me as not working very well about your
proposal is having two separate interfaces. I generally get a little
bit worried when configuration gets involved with such a basic option
-- first because most people use the default configuration (eg http://
www.codinghorror.com/blog/archives/000290.html and the problems I had
because, by default `dt act` was interactive instead of demanding
command line options) and second because that means more code to
maintain.

I think a middle ground can be found which will make everyone happy
(those who like $EDITOR and those who like interactive prompts)
without resorting to two interfaces.

[Ivan Glushkov]

Hi.

The only thing that strikes me as not working very well about your proposal
is having two separate interfaces. I generally get a little bit worried when
configuration gets involved with such a basic option -- first because most
people use the default configuration (eg
http://www.codinghorror.com/blog/archives/000290.html and
the problems I had because, by default `dt act` was interactive instead of
demanding command line options) and second because that means more code to
maintain.
I think a middle ground can be found which will make everyone happy (those
who like $EDITOR and those who like interactive prompts) without resorting
to two interfaces.

Yes, you are right, i absolutely agree with you.
But i still can't predict what version of interface users will prefer.
What do you mean when saying "middle ground". Do you see the golden mean?


Ivan

[David Wolever]

Post by Ivan Glushkov
Hi.

...I think a middle ground can be found which will make everyone
happy (those
who like $EDITOR and those who like interactive prompts) without
resorting
to two interfaces.

Yes, you are right, i absolutely agree with you.
But i still can't predict what version of interface users will prefer.
What do you mean when saying "middle ground". Do you see the golden
mean?

Well, I certainly won't claim to know the golden mean (after all, if
it were entirely up to me, I'd do away with all the interactive
prompts), but a good compromise might be defaults at the interactive
prompts, so most of the time the interaction would be:
$ dt new
GckFix the broken thing!^[:wq
^M
^M
^M
$

If you prefer to specify the bits in the ticket:
$ dt new
... set the version, target, etc ...
$

Most things interactively:
$ dt new
... add a description ... :wq
foobar^M
1.0^M
2.0^M
$

The big things I think would make life better are:
0) Having defaults at the prompts
1) Writing the message before choosing a target

But that's just my opinion.
If you'd like to get really scientific about things, I work with
about 10 other guys (and one girl) that could be coerced into doing
some usability tests.

[Ivan Glushkov]

Hello.

Let me connect to your dialog.

David, i've looked through your patch, it really good idea, i like it!
It seems that David wants us to add some new realization of entering
values into the issue (analog of UI.Menu). As i understand he suggests
not to select some item from the menu (in several steps, one after
another), but to insert them in $EDITOR.
I suppose it can be made without removing our current functionality.
We should just add new level of abstraction "choosing version from a
list". And have two implementation of that new level, choosing the
needed one from configuration.

If user likes to work in shell, he would prefer to use our current
implementation, if he wants to use $EDITOR - it is easy.

Also i propose to use some sort of comment in $EDITOR.
For example, you could get the following, when running ./dt new

Added-by: gli
Category: dt/dt -- dt/dt, dt/ui, dt/tools
Reported-for: 0.3 -- 0.3, 0.4, 0.5
Due-in: 0.4 -- 0.3, 0.4, 0.5

where current value is the "default" value from username,
etc/categories, etc/versions, respectively
and after comment sign "--" we can see available values.

David, do i correctly understand your proposition?

Ivan.

[Vlad Skvortsov]

Post by David Wolever

Post by Vlad Skvortsov
...so, am I understanding you correctly that you'd like to skip the
version selection menu altogether if there is only one version in the
"present" set? What if there are more than one? I'm talking about the
current dt UI (not about that you are proposing below).

I would like to skip as much interaction as possible, while still
ensuring that all the required fields (category, version, etc) still
exist.
Now that I've got a patch, just take a look at that and see how it
does the defaults and such :)

I've applied the patch and tried that out just now. While I found it
quite convenient actually, that reminded me of why we went the menu
direction in the first place. The version set (e.g. available versions
for an issue) depends on the category. Several categories can each have
its own version set (and it can be quite long).

The other minor annoyance was that, with that many categories and
versions as we have, my lines all got wrapped in an editor and it took
me more time to choose what I needed (dWdWdW...) than it would with the
menu.

We could put all possible versions to the issue template, but it seems
to defeat the purpose of simplifying the UI. ;-)

Post by David Wolever

Post by Vlad Skvortsov
I would prefer to keep the number of commands to minimum, especially
if there are ways to achieve the desired result using the existing
ones. By the way, if your preference is to have a separate command
for each logical action, this can be achieved by shell aliases.

[skipped]

Post by David Wolever
0) Shell aliases don't work everywhere (eg, when I use `:!...` from
Vim, aliases don't work)
1) They aren't standard -- when I go to my friend's machine, he
doesn't have my aliases, so he either has to type a lot more (using
the internal commands) or duplicate my aliases.
2) It's not very standard to require long commands for common
actions. For example, adding, moving, removing and copying are all
separate commands in svn -- it doesn't use something like `svn shell
--command=mv` (the exception, of course, is `propset`, but it's got
`propedit` too, so it's not TOO bad)

The points you are making are valid and I agree the aliases approach has
drawbacks you mention. Ok, so what actions would you propose to promote
to commands? Let's discuss that on case-by-case basis. :-)

[David Wolever]

(sorry about the delayed reply -- I've been offline the last couple
days)

Post by Vlad Skvortsov
I've applied the patch and tried that out just now. While I found
it quite convenient actually, that reminded me of why we went the
menu direction in the first place. The version set (e.g. available
versions for an issue) depends on the category. Several categories
can each have its own version set (and it can be quite long).

Yea, I couldn't think of a good way of solving that.
I don't know how people in general use it, but I've found that (with
issue tracking in general) I rarely use more than one or two
categories, so the hope was that it was "probably better than nothing".

Post by Vlad Skvortsov
We could put all possible versions to the issue template, but it
seems to defeat the purpose of simplifying the UI. ;-)

heh yes :)

Post by Vlad Skvortsov

Post by David Wolever
0) Shell aliases don't work everywhere (eg, when I use `:!...`
from Vim, aliases don't work)
1) They aren't standard -- when I go to my friend's machine, he
doesn't have my aliases, so he either has to type a lot more
(using the internal commands) or duplicate my aliases.
2) It's not very standard to require long commands for common
actions. For example, adding, moving, removing and copying are
all separate commands in svn -- it doesn't use something like `svn
shell --command=mv` (the exception, of course, is `propset`, but
it's got `propedit` too, so it's not TOO bad)

The points you are making are valid and I agree the aliases
approach has drawbacks you mention. Ok, so what actions would you
propose to promote to commands? Let's discuss that on case-by-case
basis. :-)

Ok, sounds good.

So, if I had my way, these commands would be added:
- close: accepts --fixed, --invalid or --dropped (but defaults to --
fixed)
- ed: edit a ticket, including all the headers and the body
- sh: open a shell which DT commands can be executed from.
For example:
$ dt sh

Post by Vlad Skvortsov
ls

1 open Fix the widget
2 closed Link foo to bar

Post by Vlad Skvortsov
new

... create a new ticket ...

Post by Vlad Skvortsov
close 1

... go through the steps of closing ...
Where each of the commands is identical to running `dt $cmd` from the
shell.
(I'd like this because my poor mac takes a second or two to start up,
and it's really frustrating when I've got to run two or three
commands in sequence).

So that is the list of things that I would find useful.

What do you think?

[Ivan Glushkov]

Hello.

Post by David Wolever
- close: accepts --fixed, --invalid or --dropped (but defaults to --
fixed)

May be the editor should be also invoked to enter some message?

Post by David Wolever
- ed: edit a ticket, including all the headers and the body

Do you mean creating new comment? Hm, we really can include all
previous comments and the body into the new comment (after some
delimiter - so they'll not be included in the real comment). This will
allow to see the issue in the whole.

Post by David Wolever
- sh: open a shell which DT commands can be executed from.
$ dt sh

Post by Vlad Skvortsov
ls

1 open Fix the widget
2 closed Link foo to bar

Post by Vlad Skvortsov
new

... create a new ticket ...

Post by Vlad Skvortsov
close 1

... go through the steps of closing ...
Where each of the commands is identical to running `dt $cmd` from the
shell.
(I'd like this because my poor mac takes a second or two to start up,
and it's really frustrating when I've got to run two or three
commands in sequence).

May be we should better speed up the launching time of dt? I don't
think that creating new interface is good idea, as it will complicate
everything.

Ivan.

[David Wolever]

(sorry, forgot to reply to the list the first time)

Post by Ivan Glushkov

Post by David Wolever
- close: accepts --fixed, --invalid or --dropped (but defaults to --
fixed)

May be the editor should be also invoked to enter some message?

Ah, yes, I forgot to mention that bit :)

Post by Ivan Glushkov

Post by David Wolever
- ed: edit a ticket, including all the headers and the body

Do you mean creating new comment? Hm, we really can include all
previous comments and the body into the new comment (after some
delimiter - so they'll not be included in the real comment). This will
allow to see the issue in the whole.

mmm that's a good point -- I hadn't considered the difference between
'editing the content' and 'adding a comment'.
Maybe it could be both?
I've attached (because my stupid mailer likes to mung up text) a
mockup of what it might look like.

The downside is that it's a little bit crowded -- it's not clear that
you CAN edit the NEW comment section, while you can't edit the other
ones. I don't know off hand how to fix that, though.

(hey, as a side question -- is there a wiki somewhere that could be
used for this sort of thing?)

Post by Ivan Glushkov

Post by David Wolever
(I'd like this because my poor mac takes a second or two to start up,
and it's really frustrating when I've got to run two or three
commands in sequence).

May be we should better speed up the launching time of dt? I don't
think that creating new interface is good idea, as it will complicate
everything.

Speeding up the launching of DT isn't a bad idea at all... If I have
a bit of time over the weekend I'll do some profiling and see what
can be shaved off.

I'll also whip up the shell (I _expect_ it will only be 50 or so
lines with the help of shlex) to see how useful it would actually be
(it's entirely possible the answer is "not at all") then we can get
back to talking about this particular feature.

[Vlad Skvortsov]

Post by David Wolever
Speeding up the launching of DT isn't a bad idea at all... If I have
a bit of time over the weekend I'll do some profiling and see what can
be shaved off.

Just for the record, it's i#203.

[Vlad Skvortsov]

(sorry about the delayed reply -- I've been offline the last couple days)

Nevermind, I can be out of the project for *weeks* and everyone still
tolerates me! ;-)

Post by Vlad Skvortsov
I've applied the patch and tried that out just now. While I found it
quite convenient actually, that reminded me of why we went the menu
direction in the first place. The version set (e.g. available
versions for an issue) depends on the category. Several categories
can each have its own version set (and it can be quite long).

Yea, I couldn't think of a good way of solving that.
I don't know how people in general use it, but I've found that (with
issue tracking in general) I rarely use more than one or two
categories, so the hope was that it was "probably better than nothing".

I was thinking about this issue the other day and here is what I have in
mind (we need to flesh it out, of course).

What if we modify dt to support templates? Well, actually templates for
templates as you'll see in a moment :-)

When 'dt new' is invoked with an extra argument, that argument is
treated as a template name. The templates are just files somewhere in
'issues/etc/dt/templates', so 'dt new fe' will make 'dt' use
'issues/etc/dt/templates/fe'. The template might look like:

===
Category: product/frontend
Due-in: $(VERSIONS_FUTURE)
Reported-for: $(VERSIONS_CURRENT)
...
===

So dt would go ahead and process the template and use the result as a
template for the editor (hence 'templates for templates'). Thus there
are no menus and the editor pops up immediately. Once the editor is
finished, we check the headers for consistency and if there are
problems, we tell exactly what they are and either offer some reasonable
defaults or let the user go back to the editor.

This is of course almost the same as accepting category name as a
command line argument to 'dt new', but provides additional flexibility
at (seemingly) very small cost.

How does that sound?


[skipped]

- close: accepts --fixed, --invalid or --dropped (but defaults to
--fixed)
- ed: edit a ticket, including all the headers and the body
- sh: open a shell which DT commands can be executed from.
$ dt sh

Post by Vlad Skvortsov
ls

1 open Fix the widget
2 closed Link foo to bar

Post by Vlad Skvortsov
new

... create a new ticket ...

Post by Vlad Skvortsov
close 1

... go through the steps of closing ...
Where each of the commands is identical to running `dt $cmd` from the
shell.
(I'd like this because my poor mac takes a second or two to start up,
and it's really frustrating when I've got to run two or three commands
in sequence).
So that is the list of things that I would find useful.
What do you think?

You know what, I've thought about the shell idea and I like it a lot. I
also assume that you are long for e.g. the 'close' command just because
working with current dt's command line arguments is ugly. I mean, this
is ok for scripts but for interactive work it's not as convenient.

With the shell we might improve the UI significantly without adding a
bunch of new commands. Also (what I'm missing a lot) we'd be able to use
readline and autocompletion and stuff; basically there are more
possibilities because we keep the context between commands.

So, the question is, assuming we have a 'dt shell' command with
easy-to-use commands, autocompletion, etc, would you still need these
commands you mention ('close', 'reopen', etc)?