[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: Branko Čibej <brane_at_apache.org>
Date: Mon, 17 Sep 2018 12:57:29 +0200

On 16.09.2018 22:24, Julian Foad wrote:
> In this thread we have a lot of suggestions and disagreements. I started looking for existing practices that we could copy, and here is the first thing I found. The top three hits in a DuckDuckGo search for "experimental APIs" [1] have in common the use of a run-time guard that prevents ordinary stable client software from accidentally using them by requiring an explicit acknowledgement action.
> Chrome: you must enable Experimental Extension APIs in your browser, and "the Chrome Web Store doesn't allow you to upload items that use experimental APIs".
> Windows: "By default, these APIs are disabled at runtime and calling them will result in a runtime exception."
> OpenStack: "clients must include a specific HTTP header, X-OpenStack-Manila-API-Experimental".
> That's not something we've considered before. We could think of ways to implement such a thing, but, before we go there, even just having the possibility in mind may help us think more clearly about what we wish to achieve.

The proposal to put experimental APIs (and command-line features) into a
separate namespace is a variant of this off-by-default approach. Since
Subversion is a set of libraries, we can't exclude the experimental bits
from the ABI (or rather, we can, but doing so would defeat the purpose
of having experimental bits in the first place). Instead, we force
downstream developers and users to consciously choose to use
experimental features, with all that the choice implies.

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).

As to what should be marked experimental, I maintain that my definition
elsewhere in this thread matches our original reason for introducing the
concept in the first place: to allow for developing experimental
features across multiple minor releases in a way that lets users test
them and give us feedback, yet allows us to avoid the burden of
maintaining permanent API/ABI compatibility for defunct functionality.

-- Brane
Received on 2018-09-17 12:57:39 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.