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. 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. Cheers, Daniel
