[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: Daniel Shahaf <d.s_at_daniel.shahaf.name>
Date: Wed, 12 Sep 2018 20:16:25 +0000

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_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

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.

> We should certainly mention this explicitly in the 1.11 release notes.


Received on 2018-09-12 22:16:36 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.