[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: Mon, 17 Sep 2018 12:41:09 +0000

Branko Čibej wrote on Mon, 17 Sep 2018 12:57 +0200:
> A corollary of the above is that we should never have aliases for
> experimental bits in another namespace: for example, if there is an 'svn
> x-shelve' command it should not have an 'svn shelve' alias, since that
> could lead users to believe that the feature is no longer experimental.
> Consequently, releasing experimental features to the stable set implies
> removing associated functions, types, commands, etc. from the
> experimental namespace — and yes, this *will* create ABI
> incompatibilities. If we decide that we cannot allow that and that ABI
> compatibility is more important even for experimental stuff, we can keep
> dummy functions that return APR_ENOTIMPL (we don't have to invent a new
> error code).

I agree that when an experimental feature becomes stable, it would be
good to remove it from the x- namespace in order to reinforce the
distinction that "a feature is stable iff it isn't in the experimental
namespace". (In other words: to prevent brand dilution of svn_x_*() as
a container of experimental features.)

However, while the whole point of experimental features is to provide
little or no promises of forward compatibility and provision of upgrade
paths, I suspect it won't be uncommon for an svn_x_foo() to be graduated
to a stable svn_foo() with little or no incompatible changes to its
signature and semantics. In such cases, could we keep the svn_x_*()
name around for one minor release cycle, with a warning, in order to
provide a smoother upgrade path?

That is:

    in 1.11:
        svn_error_t *svn_x_foo(SOME_SIGNATURE)
        % svn x-foo
    in 1.12:
        svn_error_t *svn_x_foo(SOME_SIGNATURE) __attribute__((warning("svn_x_foo renamed to svn_foo; the old name will be removed in 1.13")));
        svn_error_t *svn_foo(SOME_SIGNATURE);
        % svn x-foo
        svn: warning: 'x-foo' renamed to 'foo'; 'x-foo' will be removed in 1.13
        % svn foo
    in 1.13:
        svn_error_t *svn_foo(SOME_SIGNATURE);
        % svn x-foo
        svn: Unknown subcommand: 'x-foo'
        % svn foo

Again, this would only be the case if svn_x_foo()'s signature did not
change when the function was promoted to stable. We'd still reserve the
right to remove svn_x_foo() with no upgrade path, with or without adding
an svn_foo() that has a different signature to svn_x_foo(). (But as
Greg said, we shouldn't change svn_x_foo()'s signature, to preserve ABI



P.S. It goes without saying that that __attribute__() usage would be
wrapped by a macro that replaces the equivalent syntax for the local
compiler understands.
Received on 2018-09-17 14:41:25 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.