On Sun, Sep 16, 2018 at 05:13:47PM +0100, Julian Foad wrote:
> Stefan Sperling wrote:
> > I'm starting to wonder what the point of public experimental APIs really is.
> > [...]
> > What about just making such APIs private and available under include/private?
>
> subversion/include/private/README says:
> [[[
> Header files in this private/ directory are for internal APIs shared
> across Subversion's implementation. They are not part of the public
> API, nor are they ever copied into or under the include/ directory
> (e.g. by the installation process).
> ]]]
>
> In other words, we don't expose the "private" header files to downstream software.
Thanks for pointing this out. I wasn't aware of that.
Indeed it looks like the private/ directory is not a good place for
experimental public APIs, at least according to our existing policy.
> But maybe we should. Is there any practical reason not to? The argument that
> other people should not see them because we don't think they're good enough
> may not be a good argument. The argument that other people will start to
> depend on them if they are available (ignoring our warnings), and will then
> have a bad experience when we break them later, may also not be a good
> argument.
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".
Received on 2018-09-16 20:09:40 CEST