On Sun, Sep 16, 2018 at 2:09 PM Stefan Sperling <s...@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.
