[darcs-users] UI thoughts

[David Roundy]

On Thu, Apr 10, 2003 at 05:46:51PM -0700, Aaron Denney wrote:
> Having used it a couple of times, I have some thoughts:
> 
> First of all, I think it would be nice to be able to attach
> comments to patches.  The name sort of fits, but because it
> is used as an ID, there is a tendency to keep it short.

Actually, the patch format has a field for this, I just haven't gotten
around to implementing the UI to input the comments.  Partly this was
because I wasn't sure how best to go about that.  Should I ask the user
each time "Do you want to add a long comment?"? That could be a bit
annoying, to have to say 'n' each time you record a patch and don't want to
add a comment.

There's also the issue of how to input the comment field.  My leaning is to
start up an editor (based on the $EDITOR environment variable, or $VISUAL
or something) to edit a temporary file... this is mostly what has kept me
from getting around to adding this important feature.

> And generally, thinking of a name seems to make the process of making
> a patch harder than it should be.  "How descriptive should it be?  How
> hard should I try to make it mostly distinctive from existing patch
> names?" I think I'd prefer some sort of auto-generated ID instead.

Once I have the comment field active, I would say that you can make the
name as bland as you like (e.g. "bug fix"), and there's no reason you can't
use the same name every time.  Actually, a blank patch name (I think...)
would be all right, as long as you don't record two patches in the same
second (in which case they'd both have the same ID, which would be very,
very bad).  But remember that everyone who pulls your patch will see that
name, so it's a great place to put something that is really important.

For example, at work I wrote a patch yesterday that changed an API in a way
that wouldn't cause compile errors, but would make the code behave weirdly
if people didn't change their source files, so I added a big all caps note
to the patch name to notify them when they got around to pulling.

If you want an autogenerated ID, you could acheive that by creating an
alias for darcs record.  e.g. in bash:

alias drec='darcs record --patch-name "-"'

If there is enough interest in such a feature, I could also allow the user
to create environment variables controlling things like a default patch
name, much like I currently use an environment variable to determine the
default email address.

> I do like the fact that an e-mail address is part of the ID.  I wish
> the @ sign were not munged though (or at least that the munging were
> reversible).

The @ is munged only in the filename, not in the ID itself.  Now that you
point this out, it would have been a good idea to make the munging that
creates a valid filename (which has to be also a valid URL, and valid on
all platforms supported) were reversible.  But escaping the invalid
characters would make the filenames even longer...

Anyhow, the filenames are not intended to be displayed to the user.  I
believe they are only shown to the user during the darcs get --verbose, and
they are only shown there because I found it inconvenient to show the
actual IDs (which are surrounded by brackets, and can be perused in
_darcs/inventory or at the head of each patch) during the download process.

> Not backwards-compatible changes, of course, but better to break
> backward-compatibility early.

Fortunately, it has occurred to me that a change in the filename munging,
if we do want to make it reversible, could easily be acheived with a little
tool to rename all the files in _darcs/patches.   And agreed on better to
break backward-compatibility early.

> Finally, it would be nice to be able to see what the patches do before
> pulling them.  Something like "This is the raw form: ...; because
> you have the following recorded patches and pending list not in the
> repository being pulled from, it will do the following: ...;" Their
> is a cost, of course: they both require communication with the other
> repository, even if you decide not to apply, and the second also
> requires computation.  (If there were a description, seeing this would
> be nice too.)  You can look at them after the pull and then "unrecord"
> or "unpull" them, but this requires an accurate listing of the applied
> patches.  Currently, any patches that are depended on by the patches you
> accept when pulling are not printed out, so it is hard to track down
> what changed in that pull.

Yeah, I've thought about that from time to time, and agree that it would be
a good idea.  I could add a 'v' option to view the patch, so there wouldn't
be any overhead unless the user asks for it...

The only awkwardness is that I prompt first about the last patch first, and
if you want to pull it, I automatically also pull all patches it depends
on.  So when I show you what you would be pulling, I'd need to calculate
its dependencies, which means doing all the downloading for the entire
pull! So I'll just have to add a warning in the docs that pulling is
expensive.  Or I could turn things around and prompt about the first patch
first, and then if you say 'no' to it, I wouldn't prompt about any patches
that depend on it...  Hmmmm.  This sounds like a better interface, although
it'll mean hitting the 'y' key a lot more times, but on the plus side
you'll always see the name of every patch you pull.  I can also add an 'a'
choice, which would tell darcs to just pull the rest of the patches, which
would be convenient... and maybe also a --all flag.

Thanks for the suggestions! I've got to go to work soon, but either tonight
or tomorrow I'll get around to working on these changes to pull and record.
(Well, that is unless I'm too busy tracking down the reported hang in darcs
get...)
-- 
David Roundy
http://www.abridgegame.org