From patchwork Fri Dec 18 21:10:19 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mike Holmes X-Patchwork-Id: 58755 Delivered-To: patch@linaro.org Received: by 10.112.89.199 with SMTP id bq7csp1272792lbb; Fri, 18 Dec 2015 13:10:36 -0800 (PST) X-Received: by 10.140.37.100 with SMTP id q91mr7444103qgq.6.1450473036020; Fri, 18 Dec 2015 13:10:36 -0800 (PST) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id g35si17864733qgf.53.2015.12.18.13.10.35; Fri, 18 Dec 2015 13:10:35 -0800 (PST) Received-SPF: pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) client-ip=54.225.227.206; Authentication-Results: mx.google.com; spf=pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) smtp.mailfrom=lng-odp-bounces@lists.linaro.org; dkim=neutral (body hash did not verify) header.i=@linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id 20748616AB; Fri, 18 Dec 2015 21:10:35 +0000 (UTC) Authentication-Results: lists.linaro.org; dkim=fail reason="verification failed; unprotected key" header.d=linaro.org header.i=@linaro.org header.b=XnlBmSxS; dkim-adsp=none (unprotected policy); dkim-atps=neutral X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on ip-10-142-244-252 X-Spam-Level: X-Spam-Status: No, score=-2.5 required=5.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_LOW,RCVD_IN_MSPIKE_H2,T_DKIM_INVALID,URIBL_BLOCKED autolearn=disabled version=3.4.0 Received: from [127.0.0.1] (localhost [127.0.0.1]) by lists.linaro.org (Postfix) with ESMTP id 006CE615F2; Fri, 18 Dec 2015 21:10:29 +0000 (UTC) X-Original-To: lng-odp@lists.linaro.org Delivered-To: lng-odp@lists.linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id BBEEC61698; Fri, 18 Dec 2015 21:10:26 +0000 (UTC) Received: from mail-qg0-f43.google.com (mail-qg0-f43.google.com [209.85.192.43]) by lists.linaro.org (Postfix) with ESMTPS id AD373615DE for ; Fri, 18 Dec 2015 21:10:25 +0000 (UTC) Received: by mail-qg0-f43.google.com with SMTP id k90so63771739qge.0 for ; Fri, 18 Dec 2015 13:10:25 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id; bh=qUiqIL89DTDx7ej5gt3klgXwhR3VNUBaPLNb3kKh2LA=; b=XnlBmSxSJVJJHmR0E764dA5wJlBeQHI1vz+JyZlo+K+pjcrXPcCh4H2JEUY9xMd5cI 9pPIr6BxPT709yJ8cQLE5Z94tsL4lC4EqEPjvx5W/bxWoiflLKTvzfKkE5Eg+tSP4v3T SBCGylquHQdd7pN5Gwgsk6hAWWNrJHjYRalPA= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id; bh=qUiqIL89DTDx7ej5gt3klgXwhR3VNUBaPLNb3kKh2LA=; b=TlDL9UqTU6kWcMRE9Hhkom6le6bRAgVSnUTgdjnkNlV+hTB1FZn8MsVKRghmeG0GQH FTIG2zP6KHUHwcl7sTBUaQ5PrpdhD5aQs/oP3xgI0MqczA27MyYLB7JSu78iHXDJNOUx cn6G7ZEXzkgbFKoSLSeLcLEGksZbEFk29Rn4t90jTfx4kOjN33nBTNC9Wn3gMpxRFPUl sYFiU7zHGsnYAc/SRR4iozW+wA0pLu5C4rYKJhqJoR1348heIGvrNECe2QvbwBLd/SYX ZsAxp6djmUtA+h7dDWHFVV3SmgTtgtn0C68qjQwKuFVfSB/i3BV2v3XoPvK5QpiXV7AM Hz+Q== X-Gm-Message-State: ALoCoQkRbT1BVdvZOiFWFLBoEEMHtLq6yNRx9B2OY4W7uBvfH9qB5TPLn2FWX0SprTE0b/s+vCPC0nPV4RjVwzKl7lLwOBNt6w== X-Received: by 10.140.101.233 with SMTP id u96mr8197324qge.70.1450473025448; Fri, 18 Dec 2015 13:10:25 -0800 (PST) Received: from localhost.localdomain (c-98-221-136-245.hsd1.nj.comcast.net. [98.221.136.245]) by smtp.gmail.com with ESMTPSA id b80sm7584347qkb.17.2015.12.18.13.10.24 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Fri, 18 Dec 2015 13:10:24 -0800 (PST) From: Mike Holmes To: lng-odp@lists.linaro.org Date: Fri, 18 Dec 2015 16:10:19 -0500 Message-Id: <1450473019-28942-1-git-send-email-mike.holmes@linaro.org> X-Mailer: git-send-email 2.5.0 X-Topics: patch Subject: [lng-odp] [PATCH v2] doc: release-guide: add deprecated api section X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: "The OpenDataPlane \(ODP\) List" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: lng-odp-bounces@lists.linaro.org Sender: "lng-odp" Describe how changes to the public api are handled from release to release. Signed-off-by: Mike Holmes --- doc/process-guide/release-guide.adoc | 108 +++++++++++++++++++++++++++++++++++ platform/Makefile.inc | 3 + test/api_test/Makefile.am | 3 + test/validation/Makefile.am | 3 + 4 files changed, 117 insertions(+) diff --git a/doc/process-guide/release-guide.adoc b/doc/process-guide/release-guide.adoc index f5d29d2..5bef890 100644 --- a/doc/process-guide/release-guide.adoc +++ b/doc/process-guide/release-guide.adoc @@ -35,6 +35,8 @@ image::../images/simple_release_git.png[align="center"] Regular bug fixes, and implementation changes occur directly to master. + +[[anchor-1]] == Branch acceptance criteria == ODP has three branches one for general bug fixes and improvements on linux-generic, testing and examples (master). The second branch is for API @@ -134,3 +136,109 @@ made every month if sufficient change has accumulated. === Implementation (Impl) === Platform specific free form text relating to the version. + +== Deprecating part of the API +Deleting or changing the published API follows the normal <>, with the following additional rules: + +* A deprecated indication is applied to the old API using the @deprecated +doxygen syntax. +* For a function change the old API it is additionally marked using the +ODP_DEPRECATED preprocessor macro. +* The CHANGELOG will have an entry in the API change section. +* The Release Manager will resolve the duration for which the deprecated API. +will be supported, and determine which future release it will be applied to. + + +The more complex use cases are elaborated below. + +=== Changing a function +A new function will be added with the new behavior. The old function will remain and be marked by both a documentation entry and a compiler warning. +For a function change the new API will be used in the examples, test/performance and +test/miscellaneous directories. +The new API must have comparable coverage to the old API. + + +[source,c] +---- +/** + * Create a foo + * + * @deprecated This API needs to take a count and will be deleted. + * The replacement API will be odp_bar_create(); + * + * @param name ... + */ +odp_foo_t odp_foo_create(const char *name) ODP_DEPRECATED; + +/** + * Create a bar + * + * @param name ... + */ +odp_foo_t odp_bar_create(const char *name, int count); +---- + +=== Deleting a function +When deleting a function it will be be indicated in the documentation and via a +compiler warning. + +[source,c] +---- +/** + * Create a foo + * + * @deprecated This API will be removed because platforms now take care of this + * + * @param name ... + */ +odp_foo_t odp_foo_create(const char *name) ODP_DEPRECATED; +---- + +=== Changing a struct member +When changing a struct member it will be indicated in the documentation. + +[source,c] +---- +/** + * An initialization struct + */ +typedef struct foo_init_t { + /** Maximum number of worker threads */ + int num_worker; + + /** + * Maximum number of control threads + * @deprecated this is now number_of_control + */ + int num_control; + int other_items; + int number_of_control; +---- + +The implementation of the structs initialization function must be updated to cover the new element. +[source,c] +---- +void odp_foo_param_init(foo_init_t param) { + ... + param->number_of_control = 20; +} +---- + +=== Deleting a struct member +When deleting a struct member it will be indicated in the documentation. + +[source,c] +---- +/** + * An initialization struct + */ +typedef struct foo_init_t { + /** Maximum number of worker threads */ + int num_worker; + + /** + * Maximum number of control threads + * @deprecated this is no longer needed, it is automatically inferred. + */ + int num_control; + int other_items; +---- diff --git a/platform/Makefile.inc b/platform/Makefile.inc index 5d589b1..46a3baa 100644 --- a/platform/Makefile.inc +++ b/platform/Makefile.inc @@ -16,6 +16,9 @@ GIT_DESC = `$(top_srcdir)/scripts/get_impl_str.sh $(top_srcdir)` AM_CFLAGS += "-DGIT_HASH=$(GIT_DESC)" AM_CFLAGS += -DPLATFORM=${with_platform} +#The implementation will need to retain the deprecated implementation +AM_CFLAGS += -Wno-deprecated-declarations + odpapiincludedir= $(includedir)/odp/api odpapiinclude_HEADERS = \ $(top_srcdir)/include/odp/api/align.h \ diff --git a/test/api_test/Makefile.am b/test/api_test/Makefile.am index fcdba48..97ca5df 100644 --- a/test/api_test/Makefile.am +++ b/test/api_test/Makefile.am @@ -11,3 +11,6 @@ noinst_HEADERS = \ $(top_srcdir)/test/test_debug.h dist_odp_ring_SOURCES = odp_ring_test.c odp_common.c + +#The tests will need to retain the deprecated test implementation +AM_CFLAGS += -Wno-deprecated-declarations \ No newline at end of file diff --git a/test/validation/Makefile.am b/test/validation/Makefile.am index 4e36494..527e44b 100644 --- a/test/validation/Makefile.am +++ b/test/validation/Makefile.am @@ -19,3 +19,6 @@ ODP_MODULES = buffer \ system SUBDIRS = common $(ODP_MODULES) + +#The tests will need to retain the deprecated test implementation +AM_CFLAGS += -Wno-deprecated-declarations \ No newline at end of file