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

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