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
Received on 2018-09-14 18:37:09 CEST