[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: API review for 1.11; do we need to mark new APIs as experimental?

From: Daniel Shahaf <d.s_at_daniel.shahaf.name>
Date: Sun, 16 Sep 2018 12:30:24 +0000

Greg Stein wrote on Sun, 16 Sep 2018 04:16 -0500:
> On Sat, Sep 15, 2018 at 8:48 AM Greg Stein <gstein_at_gmail.com> wrote:
> >...
> > No no no... I agree with Brane above. It is confusing, and if people
> > mistakenly mix/match releases things will Just Break. Mysteriously. And
> > horribly. And possibly data-destructively.
> >
> To clarify the above a bit:
> Consider if the mid-LTS had an entrypoint with 3 parameters, [...] In
> the LTS, the entrypoint takes 5 parameters. So the function reads
> wonky stuff from the stack. Hilarity ensues.

Thanks for elaborating on that, Greg. I agree that the scenario you
describe is something we should design to prevent.

In a nutshell, I think the point is that we promise ABI forward
compatibility should deliver that even for experimental entry points.
I can think of two alternative ways to achieve this:

1. An API function marked experimental may not have its signature
   changed within a single major release line. The function may,
   however, be removed at any 1.x.0 release.

2. An API function marked experimental may neither be removed nor have
   its signature change within a single major release line (just like a
   non-experimental function); however, its implementation _may_ be
   changed in any minor (1.x.0) release to error out unconditionally,
   ideally with an error code documented in the first minor release that
   function appeared in (for forward compatibility).

   For example, If 1.11.0 adds an svn_x_foo() function, we'll also add
   an SVN_ERR_FOO error code and document that in a future minor
   release, svn_x_foo()'s implementation may do nothing and return
   SVN_ERR_FOO, and that a non-svn_x_* variant of svn_x_foo() may or may
   not be added at that time.

Would that work?


Received on 2018-09-16 14:30:34 CEST

This is an archived mail posted to the Subversion Dev mailing list.

This site is subject to the Apache Privacy Policy and the Apache Public Forum Archive Policy.