You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Julian Foad <ju...@apache.org> on 2018/09/20 15:17:38 UTC
Hide experimental APIs to unblock 1.11 release
A fresh perspective on the experimental-APIs issue just came to me: this should not hold up the 1.11 release. We were falling into the old trap of thrashing about debating how to do it, assuming we needed some solution for 1.11, but we don't. One of the rules of time-based releases: something that need not block it should not block it.
We should just pull the experimental APIs from the public API space (moving them into the private API space) and get on with the release.
This seems clearly the Right Way so I'm going to get on with it right away. Speak up if you see a show-stopper problem with that.
--
- Julian
Re: Hide experimental APIs to unblock 1.11 release
Posted by Daniel Shahaf <d....@daniel.shahaf.name>.
Julian Foad wrote on Mon, 01 Oct 2018 15:43 +0100:
> 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.
Er, no, that's not what it means. The distinction between "private" and
"experimental" is technical, not emotional. When we say something is
private we're saying, "It's an implementation detail". When we say
something is experimental we're saying, "We'd like to make this a public
API in a future minor release, please help us do so". I think that's a
useful distinction.
> 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.
Sure. If a third party has reason to use a private API, then they
should accept the risks and should work with us to promote that API
to be public.
Cheers,
Daniel
Re: Hide experimental APIs to unblock 1.11 release
Posted by Julian Foad <ju...@apache.org>.
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
Re: Hide experimental APIs to unblock 1.11 release
Posted by Branko Čibej <br...@apache.org>.
On 30.09.2018 20:51, Stefan Küng wrote:
>
>
> On Thu, Sep 20, 2018 at 10:13 PM Julian Foad <julianfoad@apache.org
> <ma...@apache.org>> wrote:
>
> Julian Foad wrote:
> > Stefan Kueng wrote:
> > > but then that would mean I wouldn't get any compiler
> > > error if I actually use a private and not just an experimental
> API.
> >
> > That's part of the point -- [...]
> > there's no real practical difference between "private" and
> > "experimental". See my notes on that topic here:
> > https://cwiki.apache.org/confluence/display/SVN/Experimental+APIs
>
> Re. wanting warnings when using private/experimental APIs: then we
> should arrange for warnings on all such functions. I think it
> makes a lot of sense to do so. Let's look for a good way to do that.
>
>
> 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.
-- Brane
Re: Hide experimental APIs to unblock 1.11 release
Posted by Stefan Küng <to...@gmail.com>.
On Thu, Sep 20, 2018 at 10:13 PM Julian Foad <ju...@apache.org> wrote:
> Julian Foad wrote:
> > Stefan Kueng wrote:
> > > but then that would mean I wouldn't get any compiler
> > > error if I actually use a private and not just an experimental API.
> >
> > That's part of the point -- [...]
> > there's no real practical difference between "private" and
> > "experimental". See my notes on that topic here:
> > https://cwiki.apache.org/confluence/display/SVN/Experimental+APIs
>
> Re. wanting warnings when using private/experimental APIs: then we should
> arrange for warnings on all such functions. I think it makes a lot of sense
> to do so. Let's look for a good way to do that.
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.
I suggest to add
subversion/include/experimental
and put the experimental headers there.
this would have the advantage that those who want to use the
experimental
features won't have to add the private folder to the compilers include
path.
Stefan
Re: Use existing __ namespace in public headers for experimental APIs to
unblock 1.11 release
Posted by Julian Foad <ju...@apache.org>.
Julian Foad wrote:
> Julian Foad wrote:
> > > One important thing I didn't make clear: I propose these APIs go in
> > > "public" headers like svn_client.h, not in the "private" header files
> > > that are by default omitted from installation.
>
> There's a nomination in the STATUS file for this change, now.
>
> Can anyone please review or otherwise comment on it?
It's approved and backported now. Thanks, Brane and Bert.
The 1.11 release is unblocked.
> > [...] The key thing was we needed to move them
> > out of the strong compatibility rules, and using the existing "__"
> > namespace is sufficient for that.
> >
> > > Stefan, does this make a difference to you? Do you still need to change
> > > TSVN build scripts at all for that case? And how will the warnings work
> > > out for you in that case? I'd really like to hear how this affects you
> > > so we can come to a satisfactory solution.
--
- Julian
Re: Use existing __ namespace in public headers for experimental APIs to
unblock 1.11 release
Posted by Julian Foad <ju...@apache.org>.
Julian Foad wrote:
> > One important thing I didn't make clear: I propose these APIs go in
> > "public" headers like svn_client.h, not in the "private" header files
> > that are by default omitted from installation.
There's a nomination in the STATUS file for this change, now.
Can anyone please review or otherwise comment on it?
> [...] The key thing was we needed to move them
> out of the strong compatibility rules, and using the existing "__"
> namespace is sufficient for that.
>
> > Stefan, does this make a difference to you? Do you still need to change
> > TSVN build scripts at all for that case? And how will the warnings work
> > out for you in that case? I'd really like to hear how this affects you
> > so we can come to a satisfactory solution.
--
- Julian
Re: Use existing __ namespace in public headers for experimental APIs to
unblock 1.11 release
Posted by Julian Foad <ju...@apache.org>.
Julian Foad wrote:
> One important thing I didn't make clear: I propose these APIs go in
> "public" headers like svn_client.h, not in the "private" header files
> that are by default omitted from installation.
Or rather, to be honest, I hadn't thought it through at the point where I sent this proposal, but now have been thinking and discussing it with others on IRC. I should not have used the word "hide" and have now changed the email subject line. The key thing was we needed to move them out of the strong compatibility rules, and using the existing "__" namespace is sufficient for that.
- Julian
> Stefan, does this make a difference to you? Do you still need to change
> TSVN build scripts at all for that case? And how will the warnings work
> out for you in that case? I'd really like to hear how this affects you
> so we can come to a satisfactory solution.
Re: Hide experimental APIs to unblock 1.11 release
Posted by Julian Foad <ju...@apache.org>.
One important thing I didn't make clear: I propose these APIs go in "public" headers like svn_client.h, not in the "private" header files that are by default omitted from installation.
Stefan, does this make a difference to you? Do you still need to change TSVN build scripts at all for that case? And how will the warnings work out for you in that case? I'd really like to hear how this affects you so we can come to a satisfactory solution.
Julian Foad wrote:
> Julian Foad wrote:
> > Stefan Kueng wrote:
> > > but then that would mean I wouldn't get any compiler
> > > error if I actually use a private and not just an experimental API.
> >
> > That's part of the point -- [...]
> > there's no real practical difference between "private" and
> > "experimental". See my notes on that topic here:
> > https://cwiki.apache.org/confluence/display/SVN/Experimental+APIs
>
> Re. wanting warnings when using private/experimental APIs: then we
> should arrange for warnings on all such functions. I think it makes a
> lot of sense to do so. Let's look for a good way to do that.
--
- Julian
Re: Hide experimental APIs to unblock 1.11 release
Posted by Julian Foad <ju...@apache.org>.
Julian Foad wrote:
> Stefan Kueng wrote:
> > but then that would mean I wouldn't get any compiler
> > error if I actually use a private and not just an experimental API.
>
> That's part of the point -- [...]
> there's no real practical difference between "private" and
> "experimental". See my notes on that topic here:
> https://cwiki.apache.org/confluence/display/SVN/Experimental+APIs
Re. wanting warnings when using private/experimental APIs: then we should arrange for warnings on all such functions. I think it makes a lot of sense to do so. Let's look for a good way to do that.
--
- Julian
Re: Hide experimental APIs to unblock 1.11 release
Posted by Julian Foad <ju...@apache.org>.
Stefan Kueng wrote:
> On 9/20/2018 5:17 PM, Julian Foad wrote:
>> We should just pull the experimental APIs from the public API space (moving them into the private API space) and get on with the release.
>
> But if they're in the private space, other clients can not use them.
> Sure, I could add some workaround in the TSVN build to pull in the
> private headers,
Clients using a build from source, like yours, can use them. I'm sorry it's more work but that seems to be the best option right now.
> but then that would mean I wouldn't get any compiler
> error if I actually use a private and not just an experimental API.
That's part of the point -- in our discussion of what an "experimental API" means there is quite a strong sentiment (myself included) that there's no real practical difference between "private" and "experimental". See my notes on that topic here:
https://cwiki.apache.org/confluence/display/SVN/Experimental+APIs
> Why not just leave it like it is for now - the docs clearly mark the
> APIs as experimental, and IMHO that's good enough (at least for now).
Because others expressed concern that if unstable functions appear in the 'public' API, these present source-code markings do not provide sufficient protection against accidental misuse and subsequent breakage. See the main thread "API review for 1.11; do we need to mark new APIs as experimental?" for the discussions.
Given the need to get 1.11 out now while we continue to work out a better way to expose the experimental APIs, does this now make sense to you as a practical interim solution?
--
- Julian
Re: Hide experimental APIs to unblock 1.11 release
Posted by Stefan Kueng <to...@gmail.com>.
On 9/20/2018 5:17 PM, Julian Foad wrote:
> A fresh perspective on the experimental-APIs issue just came to me: this should not hold up the 1.11 release. We were falling into the old trap of thrashing about debating how to do it, assuming we needed some solution for 1.11, but we don't. One of the rules of time-based releases: something that need not block it should not block it.
>
> We should just pull the experimental APIs from the public API space (moving them into the private API space) and get on with the release.
But if they're in the private space, other clients can not use them.
Sure, I could add some workaround in the TSVN build to pull in the
private headers, but then that would mean I wouldn't get any compiler
error if I actually use a private and not just an experimental API.
Why not just leave it like it is for now - the docs clearly mark the
APIs as experimental, and IMHO that's good enough (at least for now).
Stefan
--
___
oo // \\ "De Chelonian Mobile"
(_,\/ \_/ \ TortoiseSVN
\ \_/_\_/> The coolest interface to (Sub)version control
/_/ \_\ http://tortoisesvn.net