Re: svn_error_symbolic_name

Daniel Shahaf wrote:

> Prompted by Julian's review of this freshly-minted public API on IRC:
>
> 1. Question to API consumers (eg, client developers): would you find
> this API useful?  For reference, the current docstring is attached.
>
> 2. Should we print the symbolic name in release builds?  For example:
>
>     % $svn upgrade /
>     svn: E155019 (WC_INVALID_OP_ON_CWD): Can't upgrade '/' as it is
> not a working copy root
>     svn: E000002: Working copy database '/.svn/wc.db' not found
>     svn: E000002: Additional errors:
>     svn: E000002: Can't open file '/.svn/entries': No such file or
> directory
>     zsh: exit 1    $svn upgrade /
>     ### (in maintainer mode, this would show
>     ###    subversion/libsvn_wc/wc_db.c:15006:
> (apr_err=SVN_ERR_WC_INVALID_OP_ON_CWD)
>     ### as well.)

I'm not sure that's necessarily an improvement.  We recently decided to show the E155019 code to help users search.  Now
we're suggesting we might print the internal symbol as well.  Let's be a bit careful how much data we display here, and concentrate on displaying *information* (as in a useful error message).

> 3. Should the API return the error code, or the error code without the
> "SVN_ERR_" prefix?  I think stripping the error code is better because
> then users who search for the error code will be more likely to reach
> the users@ archive (with helpful posts) than commits@ archive (which
> are unlikely to contain the information they seek).  Julian disagrees,
> but I'll let him present his own case :-)

I'm not a fan of verbosity, so I think it's reasonable to leave off the prefix in the svn smdline err msgs if we do display it.  Users (and developers) will sometimes leave the prefix out when writing casually, anyway, even if it was displayed.

The API, on the other hand, should do whatever works best as an API.  We're intentionally leaving open the possibility of extending it to translate err codes that are returned by Subversion but originate from some other software layer, such as the E000002 codes in the example above.  It seems messy to stript the prefix from SVN_ERR_ if we'll also be returning non-svn err codes (and haven't decided whether we'll try to strip some prefixes from them too).  But whether the API returns the prefix or not has very little bearing on the success of users searching on the net -- that is a whole two or three social and technical levels away from the API design.

- Julian

> I also attached a patch which implements (2), in case we want it.
> (It'll be trivial to modify it to suit whichever route we pick for (2)
> and (3).
Received on 2013-04-12 19:58:31 CEST