[darcs-users] Using wrong message when rerecording

[Tommy Pettersson]

There have been discussions on command names before, and it
is a non-trivial topic.  Every person have their own slightly
different conception of what every command means, what it does,
and when to use it.  That's why we use darcs in different ways,
and why we sometimes experience: Wow, can you do this that way.

Very few people but David and maybe some others, know the exact
implications of every command (undiscovered bugs excepted)
in darcs.  But even they presumably have different usage
patterns, and thus think of the commands in different ways.

A problem with command naming is that people want (naturally)
the names to express what meaning the commands have in their
way of using darcs.

This is impossible to fulfill on a general scale, but command
names can be chosen to encourage conceptions that often predict
a correct outcome of the command, and discourage conceptions
that often predict an incorrect outcome.  This is of course
hard to do without statistical data.

The commands that by their names have caused some noticeable
amount of misconceptions (posted on this list) are annotate
and the flag --summary given to changes.  In both cases,
the misconception has been that they would not perform the
wanted operation, and they have thus been overlooked.

It might be justified to change these two names, but other
names are better left alone for now.  Many have had problems
grasping the bouquet of patch shuffling commands of darcs,
but I think the various documentations and help texts have
been improved so they now handle this.

It's hard to tell if rerecord needs a new name or better
documentation.  When I searched the list for 'rerecord'
I found one more case of this exact misconception; that
rerecord rerecords a recently unrecorded patch.  And I found
a lot of uses of the word 'rerecord' meaning "record again
an unrecorded patch".

To rename it to 'update' could cause confusion with the
very different cvs command.  I suggests 'amend' if it should
be renamed.  'rerecord' makes you think of it as a 'record',
but since it is a "dangerous" command, it might be better to
think of it as an amendment.  What do others think?


-- 
Tommy Pettersson <ptp at lysator.liu.se>