subversion-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Julian Foad <julianf...@apache.org>
Subject Re: API review for 1.11; do we need to mark new APIs as experimental?
Date Fri, 14 Sep 2018 16:37:01 GMT
Julian Foad wrote:
> 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.

I filed this proposal as issue https://issues.apache.org/jira/browse/SVN-4775 "Add x- prefix
to experimental APIs".

I have attached the required changes as two patches (one for viewspec, one for shelving) to
https://issues.apache.org/jira/browse/SVN-4775 .

Can anyone give further thoughts on whether this is definitely what we should do for 1.11?

-- 
- Julian

Mime
View raw message