From dev-return-38253-archive-asf-public=cust-asf.ponee.io@subversion.apache.org Wed Sep 12 22:16:31 2018 Return-Path: X-Original-To: archive-asf-public@cust-asf.ponee.io Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by mx-eu-01.ponee.io (Postfix) with SMTP id 8D5C2180630 for ; Wed, 12 Sep 2018 22:16:30 +0200 (CEST) Received: (qmail 63076 invoked by uid 500); 12 Sep 2018 20:16:29 -0000 Mailing-List: contact dev-help@subversion.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Delivered-To: mailing list dev@subversion.apache.org Received: (qmail 63066 invoked by uid 99); 12 Sep 2018 20:16:28 -0000 Received: from pnap-us-west-generic-nat.apache.org (HELO spamd3-us-west.apache.org) (209.188.14.142) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 12 Sep 2018 20:16:28 +0000 Received: from localhost (localhost [127.0.0.1]) by spamd3-us-west.apache.org (ASF Mail Server at spamd3-us-west.apache.org) with ESMTP id 9150418FE19 for ; Wed, 12 Sep 2018 20:16:28 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at spamd3-us-west.apache.org X-Spam-Flag: NO X-Spam-Score: -0.801 X-Spam-Level: X-Spam-Status: No, score=-0.801 tagged_above=-999 required=6.31 tests=[DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, RCVD_IN_DNSWL_LOW=-0.7, SPF_HELO_PASS=-0.001] autolearn=disabled Authentication-Results: spamd3-us-west.apache.org (amavisd-new); dkim=pass (2048-bit key) header.d=daniel.shahaf.name header.b=KhmFcMFf; dkim=pass (2048-bit key) header.d=messagingengine.com header.b=HnBiK/6h Received: from mx1-lw-eu.apache.org ([10.40.0.8]) by localhost (spamd3-us-west.apache.org [10.40.0.10]) (amavisd-new, port 10024) with ESMTP id CTxx2zyULqop for ; Wed, 12 Sep 2018 20:16:27 +0000 (UTC) Received: from out1-smtp.messagingengine.com (out1-smtp.messagingengine.com [66.111.4.25]) by mx1-lw-eu.apache.org (ASF Mail Server at mx1-lw-eu.apache.org) with ESMTPS id F16A75F485 for ; Wed, 12 Sep 2018 20:16:26 +0000 (UTC) Received: from compute3.internal (compute3.nyi.internal [10.202.2.43]) by mailout.nyi.internal (Postfix) with ESMTP id E8AE020946; Wed, 12 Sep 2018 16:16:25 -0400 (EDT) Received: from web1 ([10.202.2.211]) by compute3.internal (MEProxy); Wed, 12 Sep 2018 16:16:25 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= daniel.shahaf.name; h=content-transfer-encoding:content-type :date:from:in-reply-to:message-id:mime-version:references :subject:to:x-me-sender:x-me-sender:x-sasl-enc; s=fm1; bh=rVc2kj Qc0Hcsa9rnYeu1gXerVgxwn8HD1kcPHlD2fUM=; b=KhmFcMFfUa7A7ZkSfM5GRu XyABH3t8ugRJsOEyMPTWZZEKGZ5fcqIO1lCuUi8VBvL2eeSXff4z1vQEsmWjv7iq rgrqtZ9fi6u5rJSXBJSfWUkBW7mjXEdtaWF9ShVdYeL7n8QKG3NIoJ1+4nVa4oRq mMgUx+gilineXIjCz/AgK0VVc46JzBrr8sMCq4IsGFSden0181/0qHDcbVRAw/1M 8EUbRsiYwFphD5buGMPKVQQPb9tVWYESLIcUPvuTwXBEjEvuwhJoZthX9v/eFvxp krfS/OMRl3D8nkZJV/1szwKoVbR1Umk1kkEF3J+Y1AY3k3YsPYFAFOirlc1cwNsQ == DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=content-transfer-encoding:content-type :date:from:in-reply-to:message-id:mime-version:references :subject:to:x-me-sender:x-me-sender:x-sasl-enc; s=fm3; bh=rVc2kj Qc0Hcsa9rnYeu1gXerVgxwn8HD1kcPHlD2fUM=; b=HnBiK/6hm38ptY2G8xn0lM 49y0YUzcmbA0WmNiRiV5G4Y8ZevoCQckmdrieDLxFUMeUFF7krQvZWT9HbqD3Y52 JH9YYVauUo3H/oG+XEM0+rvDGQZxt6TJ5ckwpP/ODz6Gncq3z0oH3bXIINeSMAYg csI/qvTjBPpNYb53UFUWjKTrJSFdLhTGRQbNgupHENl4Mw0cIXCCEITWk62vrtnl iQwecPhTPJJRL5k2+0Pqq7As0bygmU+V+mMUFMqQZFHqvHZ7b5QLw2TSPW5D3r6b 9uKiGoch4/NxD1NaEw5IY9E9m6/47uc+akfyVlJNMPtk+z0BEoKk/umS/IEK1jAQ == X-ME-Proxy: X-ME-Sender: Received: by mailuser.nyi.internal (Postfix, from userid 99) id 6BCC5941AE; Wed, 12 Sep 2018 16:16:25 -0400 (EDT) Message-Id: <1536783385.674682.1506052336.1E01CBC8@webmail.messagingengine.com> From: Daniel Shahaf To: Julian Foad , dev@subversion.apache.org MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset="utf-8" X-Mailer: MessagingEngine.com Webmail Interface - ajax-1234af23 Date: Wed, 12 Sep 2018 20:16:25 +0000 Subject: Re: API review for 1.11; do we need to mark new APIs as experimental? References: <1536780086.3457949.1505951856.717CCF0B@webmail.messagingengine.com> In-Reply-To: <1536780086.3457949.1505951856.717CCF0B@webmail.messagingengine.com> 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