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
compatibility.)
Cheers,
Daniel
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.
