On 12.09.2018 22:16, Daniel Shahaf wrote:
> Julian Foad wrote on Wed, 12 Sep 2018 20:21 +0100:
>> The following public APIs are new or revved since 1.10:
>>
>> svn_client_layout_func_t
>> svn_client_layout_list
>> - New for 'viewspec' output; marked 'experimental'.
>>> svn_client_diff7
>> svn_client_diff_peg7
>> - Adds a 'pretty_print_mergeinfo' option.
>>
>> svn_client_revert4
>> svn_wc_revert6
>> - Adds an 'added_keep_local' option.
>>
>> svn_client_conflict_option_id_t
>> - 3 new enumerators.
>>
>> svn_client_shelf_*
>> - Marked 'experimental'.
>>
>> SVN_OPT_MAX_PARAGRAPHS
>> svn_opt_subcommand_desc3_t
>> svn_opt_get_canonical_subcommand3
>> svn_opt_get_option_from_code3
>> svn_opt_subcommand_takes_option4
>> svn_opt_print_generic_help3
>> svn_opt_subcommand_help4
>> svn_opt_print_help5
>> - For multi-paragraph command-line help text.
>>
>>
>> ** QUESTION **
>>
>> We recently decided that only APIs released in an LTS release will be
>> subject to our compatibility guarantees. As 1.11 is not an LTS release,
>> the above APIs will not be subject to those guarantees (until they
>> appear in an LTS).
>>
>> Do we need to do anything in the source code to emphasize that, for the
>> ones that are not already marked 'experimental'? If so, what? Mark them
>> 'experimental' in addition to their existing annotations (which probably
>> would mean we'd want to turn off the warnings about use of experimental
>> APIs in our own builds), or something else?
> I'm not sure all of these APIs need to be marked experimental. For
> example, svn_client_layout_list() is new functionality that we might not
> want to support forever, but the 'pretty_print_mergeinfo' change sounds
> pretty safe.
>
> Separately, regarding how to mark an API experimental, can we put them
> into an svn_x_* namespace, e.g., svn_x_client_foo()? When we're ready
> to declare an API stable we'll add svn_client_foo() (no "x_") and keep
> svn_x_client_foo() as a function wrapping svn_client_foo(). This way we
> can keep ABI and API compatibility for the svn_x_ name, if we want, and
> API consumers will have a clear warning sign about the experimental
> status: right in the name of the function, as opposed to some compiler
> diagnostic.
If we invent an svn_x_ namespace, we should never keep these names
available once the API is "blessed" by an LTS release. Otherwise the
experimental designation loses its purpose.
> Simply slapping an SVN_EXPERIMENTAL decorator on an API does nothing
> to alert bindings users to its experimental status; and we don't want
> bindings users to have a mistaken impression that an experimental API is
> supported, or we'd find ourselves having to support an API we didn't
> intend to.
I wonder if we can make the SVN_EXPERIMENTAL macro add appropriate
prefixes to the function name. That would leave us with *one* mechanism
to tag experimental functionality and remove that tag when it's no
longer needed.
-- Brane
Received on 2018-09-12 22:24:17 CEST