[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: Julian Foad <julianfoad_at_apache.org>
Date: Fri, 14 Sep 2018 14:56:40 +0100

Hi Daniel. Your argument makes sense.

Daniel Shahaf wrote:
> To be concrete, I propose that we have exactly two kinds of public APIs:
>
> [[[
> - Standard public APIs are supported through the end of the major
> release line (1.x, 2.x, etc) they appear in.
>
> - Experimental public APIs are named svn_x_* and are supported through
> the end of the minor release line (1.11.x, 1.12.x, etc) they appear
> in. A particular API may make stronger promises in its docstring, but
> not weaker. (If we ever need to make even weaker a promise than this,
> APIs covered by it should be in a different namespace.)
>
> Experimental public APIs may be graduated to non-experimental status
> at any minor release.
> ]]]

I would like to add, after a brief IRC discussion with brane and yourself:

- Each experimental public API SHOULD also have the "SVN_EXPERIMENTAL" function decorator (where applicable) and the "@warning EXPERIMENTAL" Doxygen tag. (These MUST NOT be used on a standard public API.)

- The 'svn' command-line UI SHOULD also use an "x-" prefix for subcommands (and "--x-" for options). However it MAY also supply aliases without the prefix.

> And I further propose that we implement this convention on the 1.11.x
> branch before 1.11.0.

I will prepare a patch, but not commit it until we have waited a bit longer for consensus, and I will get ready to roll another RC.

-- 
- Julian
Received on 2018-09-14 15:56:48 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.