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
