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

Re: API review for 1.11; do we need to mark new APIs as experimental?

From: Nathan Hartman <hartman.nathan_at_gmail.com>
Date: Sun, 16 Sep 2018 15:04:12 -0400

On Sun, Sep 16, 2018 at 2:09 PM Stefan Sperling <stsp_at_elego.de> wrote:

> I'm not sure. Exposing these APIs as private ones looked like a simple
> solution to me. On the other hand, maybe "experimental" is a designation
> which is easier for downstream users to understand as opposed to "private"
> which already has an implied meaning of "don't ever use this".
> In any case, we should consider declaring experimental APIs in
> dedicated header files, and maybe even in a separate directory.
> That might reduce the potential for confusion between "public"
> and "experimental".

There's a difference between *developer* "users" downstream and
actual users of software that uses the svn libs.

Developer users understand the difference between "private,"
"experimental," "public," etc.

Actual users shouldn't need to understand that, or be exposed to
mysterious breakage (or worse, corruption) that results from an API
changing because of an upgrade.

I think the experimental APIs should have the x_ prefix and version
number postfix that increases as development progresses; and when
an API is "blessed" the function is renamed to remove the x_ prefix
and all x_ versions of the experimental function are either removed
or made to unconditionally return an error code.

Removal means client software built against the libs will not link
(dynamically or statically), causing users to see breakage.

Returning an error code is probably a better option but many such
functions may accumulate over time -- unless they are only kept for
some predefined length of time and then ultimately removed.

I think there is no reason to add a unique error code for each removed
function because those would accumulate forever as well. Instead,
I'd create only one systemwide error code for this purpose.
Received on 2018-09-16 21:04:38 CEST

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.