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

Branko Čibej wrote:
> The proposal to put experimental APIs (and command-line features) into a
> separate namespace is a variant of this off-by-default approach. [...]
> we can't exclude the experimental bits from the ABI [...]. Instead, we force
> downstream developers and users to consciously choose to use
> experimental features, with all that the choice implies.

Using an "x-" namespace for the API identifiers only makes developers aware. Imagine the developer of GUI "svn-x" releases a version of "svn-x" that uses experimental APIs. The users have no idea about that unless the developer takes care to tell them, perhaps by releasing it in a separate distribution channel, or naming it appropriately, or putting in-app messages marking which features depend on the experimental feature APIs.

I agree that (as you said) it is that developer's responsibility to communicate that status appropriately to the users, but let's not assume it will always be obvious to the users.

The "off-by-default" approach goes further than that. It would rather map to Subversion as requiring the user to (for example) set an environment variable ("SVN_ENABLE_EXPERIMENTAL") or install an extra package ("libsvn-experimental") without which the application would either fail to run at all or fail (gracefully or not) to provide those features. We certainly could implement this approach if we wanted to, in various ways.

Now, that applies only to applications that use separately distributed svn libs. TortoiseSVN doesn't -- it bundles its own build of svn libs -- and so its users wouldn't be affected by changes to our experimental APIs, only its developers would see the changes when they try to build and test a new version.

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

I have to agree, yes.

I would quite like some users to be able to type just "svn shelve" when testing the experimental feature, but the proper way to enable that would be to allow the user to install or define aliases mapping "shelve" to "x-shelve" rather than to have these built in.

So I suppose I had better propose a patch that removes the non-x aliases.

> Consequently, releasing experimental features to the stable set implies
> removing [the experimental API] — 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 [...].

Not worth it. A client written against the experimental API is unlikely to handle that error gracefully (keeping all other functions working) unless it is a rather trivial client or was specifically designed and *tested* against that scenario.

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

Agreed.

-- 
- Julian