You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Stefan Fuhrmann <st...@wandisco.com> on 2015/04/10 01:16:35 UTC
Remaining suggested API changes for 1.9
Hi all,
Thanks to people's participation, we almost made it through
the 1.9 API review. The current status can be found here:
https://wiki.apache.org/subversion/Svn19ApiReview
Only two entries suggest an API change and are, therefore,
potential release blockers. Because they are not complicated,
I'd like to simply go ahead and change them as follows:
* svn_wc__conflict_description2_dup
Simply move this private API to svn_wc_private.h.
Ideally, people would never have called it but clients
might not have had a choice. So, we must keep it in
the ABI but remove it from the public API.
* svn_relpath_limit
This is a useful API and it is simple enough that support
in future releases should not be a problem. So, keep it
in the public API. However, it should be renamed to
svn_relpath_first_n_components because the current
name suggests something like e.g. a size limit.
Bert mentioned on IRC that he does not like the long
name to much because of formatting issues. Alternative
suggestions are very welcome.
If there are no objections, I'll commit the respective changes
Monday afternoon Texas time.
-- Stefan^2.
Re: Remaining suggested API changes for 1.9
Posted by Daniel Shahaf <d....@daniel.shahaf.name>.
Julian Foad wrote on Fri, Apr 10, 2015 at 10:20:02 +0100:
> Stefan Fuhrmann wrote:
> > * svn_wc__conflict_description2_dup
> > Simply move this private API to svn_wc_private.h.
> > Ideally, people would never have called it but clients
> > might not have had a choice. So, we must keep it in
> > the ABI but remove it from the public API.
>
> On reading this, at first I found myself wanting to argue that we have
> no duty to maintain private APIs and that we should simply delete it.
>
> Then I swung towards arguing that it's more important to avoid
> needlessly breaking apps when users upgrade the libraries (even though
> it's the app's author's fault), and so we should to keep it (at least
> in the ABI).
>
> But these arguments are not the right way to make this decision. We
> should follow our policy.
>
> If we make an individual decision in each case, then it is likely that
> upgrading our libraries will remove some proportion of the old private
> symbols and so break some of the apps that used any private symbols. A
> decision to keep one particular symbol won't help any app that also
> used another that we didn't decide to keep.
>
> So what is our policy? (We should write it down if we haven't already done so.)
>
> I can't find anything about it in our 'Deprecation' section
> <http://subversion.apache.org/docs/community-guide/releasing.html#deprecation>.
>
> If we decide to keep the code for the ABI, then the declaration may
> (I'm not sure) need to be present in svn_wc_private.h (rather than
> just local to the definition) in order to satisfy the DLL export logic
> of our Windows build system. I *think* that would be the only reason
> to keep it there. If that is the case, then we must document the
> declaration as such, otherwise one of us will come along and delete it
> later, since private symbols are generally open to deletion or
> modification at any time.
Another option: keep it in svn_wc.h protected by an '#ifdef
SVN_EXPOSE_LEGACY_DUNDER_SYMBOLS', which won't be defined by default.
API consumers that used dunder symbols from the public headers in the
past will have to add that define to their build flags. This way, new
code doesn't see the dunder symbols, but legacy code isn't needlessly
broken, either.
Daniel
("dunder" is short for "double underscore".)
Re: Remaining suggested API changes for 1.9
Posted by Stefan Fuhrmann <st...@wandisco.com>.
On Fri, Apr 10, 2015 at 7:35 PM, Branko Čibej <br...@wandisco.com> wrote:
> On 10.04.2015 11:20, Julian Foad wrote:
> > Stefan Fuhrmann wrote:
> >> * svn_wc__conflict_description2_dup
> >> Simply move this private API to svn_wc_private.h.
> >> Ideally, people would never have called it but clients
> >> might not have had a choice. So, we must keep it in
> >> the ABI but remove it from the public API.
> > On reading this, at first I found myself wanting to argue that we have
> > no duty to maintain private APIs and that we should simply delete it.
> >
> > Then I swung towards arguing that it's more important to avoid
> > needlessly breaking apps when users upgrade the libraries (even though
> > it's the app's author's fault), and so we should to keep it (at least
> > in the ABI).
> >
> > But these arguments are not the right way to make this decision. We
> > should follow our policy.
> >
> > If we make an individual decision in each case, then it is likely that
> > upgrading our libraries will remove some proportion of the old private
> > symbols and so break some of the apps that used any private symbols. A
> > decision to keep one particular symbol won't help any app that also
> > used another that we didn't decide to keep.
> >
> > So what is our policy? (We should write it down if we haven't already
> done so.)
>
>
> If it's declared in a public header, then it's a public API regardless
> of how many consecutive underscores there are in the name. We can't
> remove it.
>
Alright, less work to do for me then.
I was under the impression that we had moved some
private API from the public headers to the private sub-
folder for the 1.9 release. Hence, the proposal to do
the same here.
-- Stefan^2.
Re: Remaining suggested API changes for 1.9
Posted by Philip Martin <ph...@wandisco.com>.
Branko Čibej <br...@wandisco.com> writes:
> If it's declared in a public header, then it's a public API regardless
> of how many consecutive underscores there are in the name. We can't
> remove it.
We moved svn_sort__hash from the public header in 1.8 to the private
header in 1.9. That might have been a mistake. I see that the public
documentation for svn_sort_compare_items_as_paths still refers to the,
now private, svn_sort__hash.
--
Philip Martin | Subversion Committer
WANdisco // *Non-Stop Data*
Re: Remaining suggested API changes for 1.9
Posted by Branko Čibej <br...@wandisco.com>.
On 10.04.2015 11:20, Julian Foad wrote:
> Stefan Fuhrmann wrote:
>> * svn_wc__conflict_description2_dup
>> Simply move this private API to svn_wc_private.h.
>> Ideally, people would never have called it but clients
>> might not have had a choice. So, we must keep it in
>> the ABI but remove it from the public API.
> On reading this, at first I found myself wanting to argue that we have
> no duty to maintain private APIs and that we should simply delete it.
>
> Then I swung towards arguing that it's more important to avoid
> needlessly breaking apps when users upgrade the libraries (even though
> it's the app's author's fault), and so we should to keep it (at least
> in the ABI).
>
> But these arguments are not the right way to make this decision. We
> should follow our policy.
>
> If we make an individual decision in each case, then it is likely that
> upgrading our libraries will remove some proportion of the old private
> symbols and so break some of the apps that used any private symbols. A
> decision to keep one particular symbol won't help any app that also
> used another that we didn't decide to keep.
>
> So what is our policy? (We should write it down if we haven't already done so.)
If it's declared in a public header, then it's a public API regardless
of how many consecutive underscores there are in the name. We can't
remove it.
-- Brane
Re: Remaining suggested API changes for 1.9
Posted by Julian Foad <ju...@btopenworld.com>.
Stefan Fuhrmann wrote:
> * svn_wc__conflict_description2_dup
> Simply move this private API to svn_wc_private.h.
> Ideally, people would never have called it but clients
> might not have had a choice. So, we must keep it in
> the ABI but remove it from the public API.
On reading this, at first I found myself wanting to argue that we have
no duty to maintain private APIs and that we should simply delete it.
Then I swung towards arguing that it's more important to avoid
needlessly breaking apps when users upgrade the libraries (even though
it's the app's author's fault), and so we should to keep it (at least
in the ABI).
But these arguments are not the right way to make this decision. We
should follow our policy.
If we make an individual decision in each case, then it is likely that
upgrading our libraries will remove some proportion of the old private
symbols and so break some of the apps that used any private symbols. A
decision to keep one particular symbol won't help any app that also
used another that we didn't decide to keep.
So what is our policy? (We should write it down if we haven't already done so.)
I can't find anything about it in our 'Deprecation' section
<http://subversion.apache.org/docs/community-guide/releasing.html#deprecation>.
If we decide to keep the code for the ABI, then the declaration may
(I'm not sure) need to be present in svn_wc_private.h (rather than
just local to the definition) in order to satisfy the DLL export logic
of our Windows build system. I *think* that would be the only reason
to keep it there. If that is the case, then we must document the
declaration as such, otherwise one of us will come along and delete it
later, since private symbols are generally open to deletion or
modification at any time.
- Julian
Re: Remaining suggested API changes for 1.9
Posted by Stefan Fuhrmann <st...@wandisco.com>.
On Mon, Apr 13, 2015 at 7:33 PM, Branko Čibej <br...@wandisco.com> wrote:
> On 13.04.2015 12:23, Stefan Fuhrmann wrote:
> > On Fri, Apr 10, 2015 at 1:16 AM, Stefan Fuhrmann
> > <stefan.fuhrmann@wandisco.com <ma...@wandisco.com>>
> > wrote:
> >
> >
> > * svn_relpath_limit
> > This is a useful API and it is simple enough that support
> > in future releases should not be a problem. So, keep it
> > in the public API. However, it should be renamed to
> > svn_relpath_first_n_components because the current
> > name suggests something like e.g. a size limit.
> >
> >
> > I discussed this with Brane and he suggested
> > svn_relpath_prefix as the new name. This is
> > what Python is using and I'll go with that.
>
> What I meant is that Python uses the term "prefix" for a contiguous
> subset of path components starting at the root (see:
> os.path.commonprefix). My only interest is that we don't try to invent a
> completely new name for this concept.
>
Oh, I didn't want to imply that you were driving the rename,
that's me. I simply wanted to mention you as the person who
came up with the term "prefix".
-- Stefan^2.
Re: Remaining suggested API changes for 1.9
Posted by Branko Čibej <br...@wandisco.com>.
On 13.04.2015 12:23, Stefan Fuhrmann wrote:
> On Fri, Apr 10, 2015 at 1:16 AM, Stefan Fuhrmann
> <stefan.fuhrmann@wandisco.com <ma...@wandisco.com>>
> wrote:
>
>
> * svn_relpath_limit
> This is a useful API and it is simple enough that support
> in future releases should not be a problem. So, keep it
> in the public API. However, it should be renamed to
> svn_relpath_first_n_components because the current
> name suggests something like e.g. a size limit.
>
>
> I discussed this with Brane and he suggested
> svn_relpath_prefix as the new name. This is
> what Python is using and I'll go with that.
What I meant is that Python uses the term "prefix" for a contiguous
subset of path components starting at the root (see:
os.path.commonprefix). My only interest is that we don't try to invent a
completely new name for this concept.
-- Brane
Re: Remaining suggested API changes for 1.9
Posted by Stefan Fuhrmann <st...@wandisco.com>.
On Fri, Apr 10, 2015 at 1:16 AM, Stefan Fuhrmann <
stefan.fuhrmann@wandisco.com> wrote:
>
> * svn_relpath_limit
> This is a useful API and it is simple enough that support
> in future releases should not be a problem. So, keep it
> in the public API. However, it should be renamed to
> svn_relpath_first_n_components because the current
> name suggests something like e.g. a size limit.
>
I discussed this with Brane and he suggested
svn_relpath_prefix as the new name. This is
what Python is using and I'll go with that.
-- Stefan^2.