Compatibility-promise-less API's Re: Let's branch on Friday.

[Daniel Shahaf <da...@elego.de>]

Daniel Shahaf wrote on Thu, Apr 11, 2013 at 02:28:30 +0300:
> Ivan Zhakov wrote on Wed, Apr 10, 2013 at 23:33:01 +0400:
> > On Wed, Apr 10, 2013 at 10:02 PM, Daniel Shahaf <da...@elego.de> wrote:
> > > Ivan Zhakov wrote on Wed, Apr 10, 2013 at 21:48:39 +0400:
> > >> On Wed, Apr 10, 2013 at 9:44 PM, C. Michael Pilato <cm...@collab.net> wrote:
> > >> > On 04/10/2013 12:33 PM, Daniel Shahaf wrote:
> > >> >> Right now, trunk has APIs backing an 'svnadmin info' (or 'svnlook info')
> > >> >> command but not a UI for them.  (Some of them have unit tests.)  I think we
> > >> >> don't want to release with just the half-backed APIs, so we'll have to either
> > >> >> revert them or add a UI for them.  As far as I'm concerned reverting is fine,
> > >> >> and I can continue the work on trunk and propose for backport before, say,
> > >> >> beta1.
> > >> >
> > >> > Either revert or privatize them -- whatever's easiest.  Now's really not the
> > >> > best time to be trying to introduce new UI, methinks.
> > >> >
> > >> +1
> > >
> > > Made them conditional on -DSVN_FS_INFO.
> > I think it's better to make API private instead of ifdef:
> > 1. svn_repos.h/svn_fs.h readers might be confused with this ifdef
...
> > 2. Private API still allow to use this functionality by svn 1.8 API
> > users with disclaimer that this may change in svn 1.9.
> 
> That's unprecedented, we've never released an API "without compatibility
> promises".  We could do that but that's a separate discussion IMO.

That might be a good idea.  How about we introduce a class of public
APIs, disabled by default (i.e., opt-in towards library consumers),
which doesn't have any cross-minor-line (1.x <-> 1.y) compatibility
promises?  Or even, "doesn't have any compatibility promises", full
stop: may change arbitrarily between 1.8.x and 1.8.y.

The idea is to make new APIs more widely available for consumption and
testing; currently, the only exposure new APIs get is by (a) third party
consumers who use trunk code, (b) the alpha/beta/rc cycle.

And I nominate the svn_fs_info_*/svn_repos_info_* set of APIs to be
released in 1.8.x as part of this new "No compat" mode.  They can be
(modified as needed, and then) upgraded to the normal compatibility
rules in 1.9.x.

As to implementation, I see a few options.  We could hide those APIs
with a preprocessor flag, or name them differently (e.g.,
svn_${library}_X_*), or make them an unconditional runtime error unless
getenv("USE_SVN_X_svn_fs_info_format") != NULL, etc.

Re: Compatibility-promise-less API's Re: Let's branch on Friday.

[Stefan Sperling <st...@elego.de>]

On Thu, Apr 11, 2013 at 08:00:30AM -0400, C. Michael Pilato wrote:
> The last thing we need is a new "class" of public APIs with special promises.

I agree, it would add too much extra complexity.
Our API rules are already quite complex.

Re: Compatibility-promise-less API's Re: Let's branch on Friday.

["C. Michael Pilato" <cm...@collab.net>]

On 04/10/2013 09:50 PM, Daniel Shahaf wrote:
>> That's unprecedented, we've never released an API "without compatibility
>> promises".  We could do that but that's a separate discussion IMO.
> 
> That might be a good idea.  How about we introduce a class of public
> APIs, disabled by default (i.e., opt-in towards library consumers),
> which doesn't have any cross-minor-line (1.x <-> 1.y) compatibility
> promises?  Or even, "doesn't have any compatibility promises", full
> stop: may change arbitrarily between 1.8.x and 1.8.y.

-1

Look, if we haven't found a decent use for our own API, and we don't have a
third-party client asking specifically for its (well-defined) functionality,
then that tells us the API is unnecessary.  The last thing we need is a new
"class" of public APIs with special promises.

-- 
C. Michael Pilato <cm...@collab.net>
CollabNet   <>   www.collab.net   <>   Enterprise Cloud Development

Re: Compatibility-promise-less API's Re: Let's branch on Friday.

[Daniel Shahaf <da...@elego.de>]

Ivan Zhakov wrote on Thu, Apr 11, 2013 at 13:24:32 +0400:
> On Thu, Apr 11, 2013 at 5:50 AM, Daniel Shahaf <da...@elego.de> wrote:
> > Daniel Shahaf wrote on Thu, Apr 11, 2013 at 02:28:30 +0300:
> >> Ivan Zhakov wrote on Wed, Apr 10, 2013 at 23:33:01 +0400:
> >> > On Wed, Apr 10, 2013 at 10:02 PM, Daniel Shahaf <da...@elego.de> wrote:
> >> > > Ivan Zhakov wrote on Wed, Apr 10, 2013 at 21:48:39 +0400:
> >> > >> On Wed, Apr 10, 2013 at 9:44 PM, C. Michael Pilato <cm...@collab.net> wrote:
> >> > >> > On 04/10/2013 12:33 PM, Daniel Shahaf wrote:
> >> > >> >> Right now, trunk has APIs backing an 'svnadmin info' (or 'svnlook info')
> >> > >> >> command but not a UI for them.  (Some of them have unit tests.)  I think we
> >> > >> >> don't want to release with just the half-backed APIs, so we'll have to either
> >> > >> >> revert them or add a UI for them.  As far as I'm concerned reverting is fine,
> >> > >> >> and I can continue the work on trunk and propose for backport before, say,
> >> > >> >> beta1.
> >> > >> >
> >> > >> > Either revert or privatize them -- whatever's easiest.  Now's really not the
> >> > >> > best time to be trying to introduce new UI, methinks.
> >> > >> >
> >> > >> +1
> >> > >
> >> > > Made them conditional on -DSVN_FS_INFO.
> >> > I think it's better to make API private instead of ifdef:
> >> > 1. svn_repos.h/svn_fs.h readers might be confused with this ifdef
> > ...
> >> > 2. Private API still allow to use this functionality by svn 1.8 API
> >> > users with disclaimer that this may change in svn 1.9.
> >>
> >> That's unprecedented, we've never released an API "without compatibility
> >> promises".  We could do that but that's a separate discussion IMO.
> >
> I believe that we do not promise compatibility for private API.

We also don't permit code we didn't write to call such APIs.  (e.g., we
don't install include/private/ during 'make install' --- just like we
don't install subversion/libsvn_*/*.h)

Re: Compatibility-promise-less API's Re: Let's branch on Friday.

[Ivan Zhakov <iv...@visualsvn.com>]

On Thu, Apr 11, 2013 at 5:50 AM, Daniel Shahaf <da...@elego.de> wrote:
> Daniel Shahaf wrote on Thu, Apr 11, 2013 at 02:28:30 +0300:
>> Ivan Zhakov wrote on Wed, Apr 10, 2013 at 23:33:01 +0400:
>> > On Wed, Apr 10, 2013 at 10:02 PM, Daniel Shahaf <da...@elego.de> wrote:
>> > > Ivan Zhakov wrote on Wed, Apr 10, 2013 at 21:48:39 +0400:
>> > >> On Wed, Apr 10, 2013 at 9:44 PM, C. Michael Pilato <cm...@collab.net> wrote:
>> > >> > On 04/10/2013 12:33 PM, Daniel Shahaf wrote:
>> > >> >> Right now, trunk has APIs backing an 'svnadmin info' (or 'svnlook info')
>> > >> >> command but not a UI for them.  (Some of them have unit tests.)  I think we
>> > >> >> don't want to release with just the half-backed APIs, so we'll have to either
>> > >> >> revert them or add a UI for them.  As far as I'm concerned reverting is fine,
>> > >> >> and I can continue the work on trunk and propose for backport before, say,
>> > >> >> beta1.
>> > >> >
>> > >> > Either revert or privatize them -- whatever's easiest.  Now's really not the
>> > >> > best time to be trying to introduce new UI, methinks.
>> > >> >
>> > >> +1
>> > >
>> > > Made them conditional on -DSVN_FS_INFO.
>> > I think it's better to make API private instead of ifdef:
>> > 1. svn_repos.h/svn_fs.h readers might be confused with this ifdef
> ...
>> > 2. Private API still allow to use this functionality by svn 1.8 API
>> > users with disclaimer that this may change in svn 1.9.
>>
>> That's unprecedented, we've never released an API "without compatibility
>> promises".  We could do that but that's a separate discussion IMO.
>
I believe that we do not promise compatibility for private API.


-- 
Ivan Zhakov