[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: Suggestion: "svn explain"

From: Martin Pool <mbp_at_sourcefrog.net>
Date: 2002-08-04 03:11:17 CEST

On 3 Aug 2002, Gareth McCaughan <Gareth.McCaughan@pobox.com> wrote:
> On Saturday 03 August 2002 3:22 pm, Martin Pool wrote:

> 1. I see nothing that guarantees that the error IDs will never
> change. They're allocated sequentially-by-magic in
> svn_error_codes.h, and if someone ever adds a new one
> then all the later errors will get their IDs bumped up. Since
> they are (currently) arranged in groups, it seems quite
> likely that errors will get added in the middle of the list.

I think if Subversion exposes error codes in messages, people will
count on them to be the same. Changing them would be confusing.

> 2. It's possible that the most appropriate message will
> need to change from one version to the next. For instance:
> I recently found what I think is a bug that leads to an
> incorrect "Transaction out of date" error. If I'm right to
> think it's a bug, and if it turns out to be easy to work
> around and hard to fix, then for a few versions it might
> be beneficial to add something to the corresponding
> error description along the lines of "There's a known
> problem with the version of Subversion you're using
> that sometimes causes this error. Try doing X instead,
> or see if the problem has been fixed in the latest version.".

It seems to me that this is an argument for not having the detailed
explanation not stored in the binary, but rather somewhere it can be
more easily updated. Some people will in 2004 be using e.g. the
RedHat build of Subversion from 2003, which will probably contain bugs
that were not known at the time of release.

> Looking back at a thread from mid-July (don't know how
> I missed it before), I see Ben suggesting a "svn help"
> feature along similar-ish lines, Karl -0 on it, Brian Fitzpatrick
> -1, and a certain Martin Pool actively in support. :-)

What I was proposing was adding help messages for things like
svn:keywords, or indeed a "subversion keywords" command. I would
argue that it's "inside the line" of reasonable on-board documentation
because it can be very concise, users will probably not remember the
magic names and will appreciate help, and it will not change much
between versions.

Thinking about error messages more: for most other programs, just
typing the error message into Google will get you a good explanation,
from a manual, faq, or mailing list archive. The important thing is
to write the documentation, not to put it into the binary.

-- 
Martin 
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Sun Aug 4 03:12:47 2002

This is an archived mail posted to the Subversion Dev mailing list.

This site is subject to the Apache Privacy Policy and the Apache Public Forum Archive Policy.