Re: Hide experimental APIs to unblock 1.11 release

Branko Čibej wrote:
> Stefan Küng wrote:
> > How about moving the experimental headers into a separate subfolder?
> > Right now, there's:
> > subversion/include
> > subversion/include/private
> > and the experimental headers are now in subversion/include/private.
>
> No they are not. The shelving functions, for example, are declared in
> subversion/include/svn_client.h. Private functions are in
> subversion/include/private, but those are should not be used outside the
> Subversion libraries.

My view is expressed in the "Private APIs" section on https://cwiki.apache.org/confluence/display/SVN/Experimental+APIs

The very terms we use both betray and influence our attitude. "Private" implies "go away, don't look, don't touch", whereas "unstable" or "experimental" or "internal" can imply this is the place where further open source development can take place.
 
We should stop making a distinction between "private" and "experimental" and just say that everything not declared as public is in the same bucket, available for interested developers to look at and use -- that's the nature of open source software.

If we declare X as "private" and Y as "experimental" that's just like saying please don't try to use X, although we use it. It makes us uncomfortable. We've forgotten how it works ourselves and don't want to deal with anybody wanting to get involved in using the software at that level of integration. Don't go making us look at it again and reminding us how bad it is; we've got other things to do. But please do take a look at Y, try using it, and give us your feedback on it. It's a matter of attitude, not a hard distinction.

Instead, I would rather we start to say "Dear developer, if you look into Subversion and find yourself needing functionality which is currently not supported by public APIs, please do figure out how it works using the internal APIs and then try to bring us a proposal for a public API that would support your needs." I think that's a healthy approach.

-- 
- Julian