"cvs [commit aborted]: cannot commit files as 'root'"

[Lenny Foner]

    Date: Sun,  8 Jul 2001 18:28:50 -0400 (EDT)
    From: address@hidden (Greg A. Woods)

    [ On Sunday, July 8, 2001 at 16:00:55 (-0400), Lenny Foner wrote: ]
    > Subject: "cvs [commit aborted]: cannot commit files as 'root'"
    >
    > You know, given how often people ask this question, maybe some
    > paragraph of your response here should be put INTO THE ERROR
    > MESSAGE ITSELF.

    Well actually I would have thought the message was already very very
    clear all by itself -- if maybe a bit terse for anyone with English as a
    second language.  It does, after all, say exactly what it means.

No, it only says that you can't.  It doesn't explain WHY, which was
precisely the question that was asked.  Nor, apparently, does it help
anyone who ever gets it---they say, "Yeah, so, I'm root.  What's the
big deal?"  And then (a) they waste their time asking the list, and
(b) they waste all -our- time reading their question, and (c) they
waste a few peoples' time who answer them.  Seems suboptimal to me...

    Maybe if it said "You, whomever you are, cannot commit files as 'root'!"
    (complete with the explanation mark :-)

That doesn't help the users, whose immediate next question is, "why not?"

    That's not a real suggestion though -- CVS error messages should remain
    as stable as possible so as to facilitate ease of maintenance of wrapper
    and front-end programs.

You're kidding, right?

You're actually arguing that error messages must remain fixed for all
time because someone might have based a wrapper on them?  Whatever
happened to the concept of exit codes?  Whatever happened to the
concept of the localization of all text emitted by a program for the
user's native language?  Whatever happened to any pretense of design,
not to mention professionalism?

If that's -really- the concern, then I submit that a much more stable
mechanism would be to number all the error messages uniquely, and emit
that number (perhaps surrounded by some sequence of characters not
ever used elsewhere in error messages---though be careful of
filenames! probably it needs to be ina known location, like the start)
along with the error text.  And, of course, the easiest way to do that
would be to put all the error messages in a big enumeration, which
guarantees no duplicated numbers (because it's the compiler assigning
the numbers), and makes internationalization simply a matter of
translating the messages that appear in that table---which is probably
in a single file.  This isn't rocket science---it's how any number of
programs are actually written.  Obviously, you have to make sure that
nobody ever inserts a new message in the middle and upsets the
numbers, but hey, that's easy enough to enforce---in sanity.sh if
necessary.  (Or, you move away from numbers entirely, and use unique
strings---checked by whatever routine builds the table to -guarantee-
that they are, in fact, unique---hence avoiding any ordering at all.
This is how VAX/VMS did it, so typical error messages that looked
like "DCL-F-NOFILE, no such file FOOBAR" and you know what emitted the
message [DCL], how bad it was [fatal], and had a unique string if you
really wanted to search for it in a logfile [NOFILE].)

Hence, a typical CVS error message might instead look like:

  ##CVS-Error 23##:  cvs [commit aborted]: cannot commit files as 'root'

  Since root is usually a shared account, CVS won't allow you to commit
  as root unless it can figure out who you really are.  Logging in as
  yourself and then su'ing to root will usually allow CVS to figure out
  who you are, but logging in as root won't.  If you're sure you want to
  be able to commit as root, see CVS_BADROOT in src/options.h.  For more
  information, see section 23.4.5 of the manual, or http://foo/bar.html.

Wrappers can search for the "##CVS-Error 23##".  Users can ignore that
part, though they can use it in bug reports as a shorthand.  But users
-do- get something that actually explains what they did wrong, exactly
where and when they need it, and without forcing a shift of attention.
Those attention shifts are very costly in terms of productivity.

    I think what maybe surprises people about this is that usually 'root'
    can do anything and usually error messages say "you must be root to...."
    Obviously though a source code control system has different security
    requirements than a filesystem.

In this particular case, you may (or may not) be correct about what it
is that "surprises people".  I'm making a more-general argument than
just this particular error message, of course.

    > Yeah, I know, I know, everyone will say "that's why you're supposed
    > to read the manual!", but it's obvious that either (a) people aren't
    > reading it well enough, or (b) it's a little too buried.

    It isn't even in the manual, as far as I can see.  That's maybe the
    worst failing of the manual -- there's no (even partial) list of the
    error messages in one place with links to nodes containing their
    explanations.

Yup, that sounds like a pretty bad failing, all right.  Of course, the
structure of the CVS code makes it a giant pain to actually make sure
that the manual mentions all the error messages, right?  Design error.

Sounds like sanity.sh should be amended to do a grep for every error
message through the manual and at least make sure that it appears
-somewhere-.  Sure, that won't help you to make sure that the message
is described clearly and well, but at least it tells you if you forgot
to mention it at all...

    > My basic point here is that, industry-wide, far too many error
    > messages are far too terse.  They should include paragraphs of prose,
    > pointers to manual sections, URLs for further clarification---and
    > probably all -three- of them.  Why not?

    Why?  What a waste of space, energy, resources, time, effort, etc.!

Because one implementor's effort saves n thousand people's time,
that's why.  Otherwise, you might as well argue that every individual
user should just reimplement their own CVS from the ground up, yes?
Surely the person who -wrote- the code understands -why- it's emitting
some particular error message.  A couple minutes' work (if that) to
make the error message really explain what's going on is a single sunk
cost, but it could save an enormous amount of time for all your users.
If 1000 users/year get this error, and it causes them to spend one
minute reading the message instead of 10 minutes looking for something
relevant in the manual, the developer has just saved 10,000 minutes/yr
for the user base, which is 166h or just about ONE MAN-WEEK.  All for
a 2-minute investment.  Sounds like a pretty good return to -me-...
And that's not counting cases where it's not a trip to the manual, but
a trip to a mailing list, which waste's much more of the user's time,
and those of the people on the list, too...

    All that's really necessary is that the documentation contain
    descriptions of the error messages.  With 'info' documentation the
    searching for the meaning is extremely simple.

Why force the user through an extra step?  He's already staring at the
message.  Why not help him to understand what he's looking at?

    I really rather dislike execessive verbosity in error messages.

Is telling the user what he did wrong, and why, "excessive"?  You
sound like you're saying that all CVS error messages should simply be
"?", like a certain well-known text editor from the early 70's, when
memory was many cents/bit.  Or perhaps they should just be "abend 34117";
after all, that's what the manual is for, right?

Inscrutible error messages may be -your- preference, but such
preferences tend to be associated with people who think that everyone
should be as elite as they are, or else get out of the pool.  It
doesn't help most users---after all, they have a job to do, and that
job is not to become intimately familiar with the tool.  The tool is
only there to help them get some other job done, so they'll typically
only learn enough about it for them to get the rest of the job done.
Just because -some- people can disassemble their car's engine and put
it back together is no reason to assume (or insist) that people who
just want to drive to work need to know how to do so.  And even the
professionals expect some help---that's why most cars put the cylinder
firing order ON THE ENGINE BLOCK or nearby, to avoid wasting time on a
possibly error-prone trip to the manual.

    Specifically for CVS though error messages should be kept as stable as
    possible and short enough that when fully formatted with an average
    filename they don't exceed 80 characters in length.

Once again, if you need stability, make that a representational
invariant of the message, via some unique string, but don't make that
string also do double duty by being intelligible to users.  Make the
intelligibility part separate, so error messages may be made
understandable and also translatable.

    >  After all, we're no longer
    > using 300 baud teletypes where a long error message takes a minute to
    > sit through.  Nor does it matter if the executable is 10K larger
    > because the error messages actually tell you what's wrong---not in an
    > era of 1G OS's and 10M applications...

    Size and speed aren't everything (though they're certainly still very
    very important -- far more important than you seem to think!).

Let's assume that CVS can emit 100 different error messages.  Let's
also assume that they average 100 bytes each, and that we increase
their size by a factor of 10, so they each average 1K.  (That's a
fairly large error message, btw---my sample above is only half that.)
We have now added 90K to the size of the CVS image, assuming that all
error-message text is loaded with the image (certainly the easy way to
do it).

What does this 90K cost us?  A typical workstation these days might
have 64M of memory, so this is 1 part in 711 of its total memory, or
0.14% of its available memory---and only during the instant while CVS
is actually executing some command, of course.  Of course, if memory
is -that- tight, you'd better not load even a single jpg into your web
browser---those tend to be around 90K or so...

How much longer will it take to load the binary image, given that it's
90K longer?  Even if your disk only gives you 1MB/sec (pitifully slow),
it means it takes CVS one tenth of one second longer to load into
memory.  And that's assuming (a) no sharing of the image with other
processes, if they're using it, (b) no filesystem caching, and (c) the
slowest disk I've seen in years---all for a program that (a) takes
much longer than 100ms to do much of anything, and (b) is almost
always called interactively, where a tenth of a second will never be
noticed by the user.

On the other hand, the user -does- notice spending several minutes
looking something up in a manual, or several hours to several days
waiting on the turnaround of a mailing list.

    Maintenance is also incredibly important.  I think it's far better to
    have very good documentation and to keep it up-to-date with lists and
    descriptions of error messages rather than to have to maintain the same
    text in both the code and the documentation (or come up with some
    convoluted scheme to try to merge one from the other).

Keeping documentation up-to-date is often neglected.  Keeping the
documentation in the code tends to make it more likely to be
maintained.  Besides, it's obvious that the documentation wasn't kept
up-to-date in this case anyway, so you can't exactly make an argument
that it is in better shape than the code on this issue.