From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from EUR01-HE1-obe.outbound.protection.outlook.com (mail-he1eur01on0071.outbound.protection.outlook.com [104.47.0.71]) by dpdk.org (Postfix) with ESMTP id 6A1A72C8 for ; Fri, 25 May 2018 14:08:02 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nxp.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=e3ZNAE9yWGherOb5aGHeIhnduy8Kkfx2IhQoDOKYc5Q=; b=D5uA+auxBcgSbCk3XsMY8Q2tdJR3L8pfUyTRiBdGsKKa64/MX9PlRSJqmkOrPVji7lCxMBCkIRInt0YdnqojsJUm31ojVPV86295BGb/R0Mcpx8GKauIHBZ+F0Rcb4lKYWka+oNHRtDIe+FBZuqbGZnwUXdbXv0jJmdHsmG/+pk= Received: from Tophie.ap.freescale.net (14.142.187.166) by VI1PR0402MB2782.eurprd04.prod.outlook.com (2603:10a6:800:ad::12) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384_P256) id 15.20.797.11; Fri, 25 May 2018 12:07:59 +0000 From: Shreyansh Jain To: thomas@monjalon.net, bluca@debian.org, nhorman@tuxdriver.com Cc: dev@dpdk.org, Shreyansh Jain Date: Fri, 25 May 2018 17:37:33 +0530 Message-Id: <20180525120733.1534-1-shreyansh.jain@nxp.com> X-Mailer: git-send-email 2.17.0 MIME-Version: 1.0 Content-Type: text/plain X-Originating-IP: [14.142.187.166] X-ClientProxiedBy: BM1PR01CA0112.INDPRD01.PROD.OUTLOOK.COM (2603:1096:b00::28) To VI1PR0402MB2782.eurprd04.prod.outlook.com (2603:10a6:800:ad::12) X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-HT: Tenant X-Microsoft-Antispam: UriScan:; BCL:0; PCL:0; RULEID:(7020095)(4652020)(5600026)(48565401081)(4534165)(7168020)(4627221)(201703031133081)(201702281549075)(2017052603328)(7153060)(7193020); SRVR:VI1PR0402MB2782; X-Microsoft-Exchange-Diagnostics: 1; VI1PR0402MB2782; 3:V3Org+i6IuzMzZ03wwvvHvnOSUs5Pw204Se9jnaghIpaj3/d3b4/01Hdy+IH5Kdjw1CRRgE0jIMEgX80slW72zZKik658vGCuVTjn94k6+flXfxgd/ftQQd0L0DV2B96810GCgC1UYjKi0XzijfSbafMMYiXjpKk5s6V/Ynob3oR1gyGKXhdfNkHVukEvXAhu33zEkVehb8nkI/MuQbtfmZ0O7TBL+9NQg/J2wu0JYklhSek1KnTu24LcQ86PCus; 25:cyRT2W/AlnAy4ex89AhpbfPd6Ds27cdMYVCMc+JzLtk7NH3oDhymP9GsvMQOh7X1GYI5Yyi//puOTL7HRw4yP9+tsWwMhfl8GiW7lWYjHhA0epMLS1tIZ5wkV7K+HLys+TpDnpHENInn53ZltGcSgyPUqbCjmLhsmOAhQqWHqMQRCwC1eRUPWUUP7alI2xzl4V8yO+9+1cAcWft6YgqUFbxnWT52vbi9QQYy3YqEMf1B0RbYzLkhHRt6WFO4EHu6v5qdCJJQeOHKWQFcHi9rPLcB9lhYKnUMQqn9llTSPwx6hh6Po05h1ut3SU97EsPQOygvjgFtwQleNi1pu85pqQ==; 31:SxLC5MTMMv0Ov51nyPBh3bcJdNVghlPc7RJUl55quSd+BQGAhhsCOS7s1X2TsOfQFyjMS2/9dOMuyQ4xy76IDADUSr+YXc5S5VXYNBYe3keMsD/0YsACwVwx80bJ1yRkTMMEUqLo77CegZQZ9B9+yB7pRz/F9y+dejk/3z4p3uvk9V9eHOZEPLmOl8ziBkeVcgiM8p+5B6D/KVWKaSY/HUA2rA3C6NzVm5kx3UjoJIY= X-MS-TrafficTypeDiagnostic: VI1PR0402MB2782: Authentication-Results: spf=none (sender IP is ) smtp.mailfrom=shreyansh.jain@nxp.com; X-Microsoft-Exchange-Diagnostics: 1; VI1PR0402MB2782; 20:/zWoUucXY220DHE5YRzLd+dTNftzTTrSi4I9w1UbOlxJbNUSqTGELLXO/Jkq65lUHb1ToLDN30q6ftsowqnraZrUEPxPkBbtbKn6xpeUw3acjQrPwxVAt15e5+9je1vOjOTmEB1+zqAvFadBxq+FpOzYAxCpawfUEiGb4JDoW8npNF+FtRqKosHej6FLTbYHZ3z8WHW/CyllG6hD/tW91jzPk/hFymxGzeYiWGcVA5zrwEOh8bIAoiZbQ9f9GZ+LocWa9w8VaKiX/978qKEmI6R96bXJaiFv89SUa201wXEO/85UpwfTCAx2gZMDdjbXhrSStK2qU0hGpkWobUG9+9qfZchiSTHfQd7E/jDqrICZRcE6QIh/oFZKecxHDUJm3/TBPrQVKCTzfo7mCUHcVEEPKgW9WfaYkblx8H27O1uJvq8o6+ZJ1vLSHJIMF9Ko4TuaJFgXPZMZ5+GYs6w7yPubTIt/HIWv9KgpWa/xe/H/DHpeYinDxM9Bu7IYI0uc; 4:vs3D1euaXobGu0NZTj3k73fFcpX8HhlrH7wrck1Ztj45m3brO2juoUFozhsJtMVCVtzCqnM4A6oXtmevXuno8ZLKiZjbv/YXdTpboWtdSLNdCEf9PbUS0ZDHMgf9WVSEEYkwAOd9z3IKGsmQpFskAHcjQVhBNjm7qUs/QWL8aQTTbjAQHKXhFmw6tQM4KcFZW+RtggZmn5gEdwTAgrT5VXwVb2sNZViuw8hxLKh+cokEiXxBkc7Sz1jhhpOk4M64iWXO+vx6Oc96QULgwq20LByzVbN2yQkDhXqz6xflCDOEAjM9ycu67pQpUyQEuQiy X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-Test: UriScan:(185117386973197); X-MS-Exchange-SenderADCheck: 1 X-Exchange-Antispam-Report-CFA-Test: BCL:0; PCL:0; RULEID:(8211001083)(6040522)(2401047)(8121501046)(5005006)(93006095)(93001095)(10201501046)(3231254)(944501410)(52105095)(3002001)(6055026)(149027)(150027)(6041310)(20161123562045)(201703131423095)(201702281528075)(20161123555045)(201703061421075)(201703061406153)(20161123560045)(20161123558120)(20161123564045)(6072148)(201708071742011)(7699016); SRVR:VI1PR0402MB2782; BCL:0; PCL:0; RULEID:; SRVR:VI1PR0402MB2782; X-Forefront-PRVS: 06833C6A67 X-Forefront-Antispam-Report: SFV:NSPM; SFS:(10009020)(346002)(376002)(396003)(39380400002)(39860400002)(366004)(189003)(199004)(305945005)(486006)(1857600001)(316002)(7736002)(47776003)(44832011)(66066001)(16586007)(6116002)(3846002)(106356001)(16526019)(53936002)(51416003)(52116002)(105586002)(6512007)(26005)(86362001)(186003)(956004)(2616005)(59450400001)(6506007)(386003)(476003)(8676002)(1076002)(55236004)(478600001)(5009440100003)(15650500001)(50466002)(6486002)(81166006)(4326008)(81156014)(97736004)(6666003)(48376002)(50226002)(36756003)(2906002)(25786009)(5660300001)(8936002)(68736007)(110426005); DIR:OUT; SFP:1101; SCL:1; SRVR:VI1PR0402MB2782; H:Tophie.ap.freescale.net; FPR:; SPF:None; LANG:en; PTR:InfoNoRecords; MX:1; A:1; Received-SPF: None (protection.outlook.com: nxp.com does not designate permitted sender hosts) X-Microsoft-Exchange-Diagnostics: =?us-ascii?Q?1; VI1PR0402MB2782; 23:InHjxSDruyHHePC5yVv5ZGS03ad5Bw3K1S75Gbl?= =?us-ascii?Q?0aIdOecCWQDYN2bGJPfr+taPYXOIF1XXxQbQu2Hanff8bpjhef+R3WRdcikB?= =?us-ascii?Q?zoUwzYM4KHKXv508LOQaVbZVR7P2JaDe1DVBnBynQUyONMbVFoaJ7mtpdXSz?= =?us-ascii?Q?u61YE/uZXArzeybA3m9isyISTXZ+NTshLizCEYnKzDEpyc08Iz5kj7soAX0B?= =?us-ascii?Q?JkC0OxroPFI3SaCxmye8XURIvKKDHnNJdAgtDJx8uduadc2ZaTyYD7jSEujR?= =?us-ascii?Q?qmS4ZK1esi801+o8T0R0SbSb4Mul0H4ITQh6t+TL1l81viDv6CJ4shLds6lV?= =?us-ascii?Q?JPQJuZ0Ir0K4cpp5yAUQuJJ/mVuoxczVF5DUC8JlpbvALe/2s5N0fhjlhDz0?= =?us-ascii?Q?+S4VvPsw62/aEIiq4DHwN0/WZc3wl6Wvgtfgy13mjb79u+5cJSv/JE3En4gn?= =?us-ascii?Q?68C2YcqbMdaO2zK4Don+RdMbEipchcoOh+96hui7uPA5zK6Uspp7T34H01ik?= =?us-ascii?Q?PJzNHrnswnqgL5nOiUh9D8/XhbVoZrH+VYHTMQ1wIweTznnOhBOWXA4t00aB?= =?us-ascii?Q?HTdMFrZueXx0mpGLwhxfue1GPlsRKUYuoI4y6YO0dweejb5Oo6H8m+SKEwu4?= =?us-ascii?Q?r1cKlQerdUpWDqiUdij7JCCCS0GtHra+NYwuBZ200X6cDXg1uPcWK4AumrFS?= =?us-ascii?Q?Yvhmtd17RV7wWw+ZGn7kPHMahu24IdjZp1BVlXmDNC5dFC9tfTBpUxs5/oYN?= =?us-ascii?Q?f/AHr6B6BIjkV6ddXubJ8HyuUTYlPY+MVy91cSR1VCzXHMkAS7fayHu7Kfeb?= =?us-ascii?Q?TrKAyUBy7Ghp4BNwjxkS4jA1NmJ41zJ5zDri27tS04ofys01Di2ENRJ+sRvO?= =?us-ascii?Q?Ejl+MAC1F+9VEnhyIxybBy3y+yORN6g8nNJQ2gkhiIFvMie0pUmLW1hl2VQy?= =?us-ascii?Q?r8kKpEhT94ca7UA30V9SLIf7RoYlAhCppWhsva7mSz3Pn66mGhAGCTI0WdL9?= =?us-ascii?Q?wLvo7JVc+TTQGQapzBUfxVK1ENMZFj4oGDe0f7ANjk5m+F9Ks1BM0k3cUJkP?= =?us-ascii?Q?ssHiTcfH1ZbZtOt6LVwT3v039WV1Lu0AIag/SKvfkzOy9xiJtiH3jhpCJaqX?= =?us-ascii?Q?FFudhKdKNefggCdS/rJbxXZROOQ3wroFVaIK63Feg8IEyfFFY/7nDt8F7INR?= =?us-ascii?Q?nBfKkL0QcC3ZoO/GGAsV3qk9YStLPfqIIS4gOOtG/mmMom4Sifr7iC04icO1?= =?us-ascii?Q?u48uUwNjHpPbLAyDnqId+dDEQ2Y7vu6sehYmTRf/nsI1kD8kg4KypYZAG00L?= =?us-ascii?Q?2qQ=3D=3D?= X-Microsoft-Antispam-Message-Info: ZbZB6vMLxPzyXv94I98mQQWY+WQVPo6J+//vDP5bjYVrGgIWVLk/VJ0elXTxh6z5gLnQ3qJ5ztDfhTyuZtnBl4z5/3nH35pUA0qfvdtjr/JTjkp3R0f20gEwgxjF3D07u1ZUBoP1iY0h9/zVpR1GrSC0VVeUewDfEpJQhoEvbt+6FFRnsCNGbipAjtT8ICK7 X-Microsoft-Exchange-Diagnostics: 1; VI1PR0402MB2782; 6:ibYIvEA72uuNu96oQmyAaiHHWzLmwxUVnWrunj8I3QK+DwdlXqJO/i1CJQ2uSBDXqMdostC2CUw1YluDwupTI+Ym/2GZApHTp4l6G7hRTFcowSJrqQ52u6Io0Z2xtv2wWt2tJ3638rDZRoCpKUlRWCFdUDL6FyZgNhPy0ZE3nEa6JH57JQzGe1zfvvY9tEx6By61tmGHLWDuQOI6PutlyjvXnfHMx2lOc5fWIA8MKNA5lTFokfVU5chddadU35nEQmSYzsFnHMsyQK6x7FQO9avtcVuXs/0ey/x7m+eSYCVI8uQDJK3VsxyAVrAymv21UmIsy5jm//IKP8Ab/sS206G8aLQHrprYQ60rUj/T+Gmx3YCe/JAoIA+eF9fKFZvCMxupEQT2dkdELKgn3uub+FsmSJAJcLFJLY956GBLSbEusfQ/e2fsA+pmyfDHT5Ro3v+I9IEJmLTNh9cZW2ucEw==; 5:5tLU5mmzOL8Nmm4CJFQG1sv4JqKV5KxAfTkIguLZNzw+B7i9zVc5ou/VVhw1rKjjYxNSK6T3iBmVda1x2hle9Ou0JWcFiD7tWYt9EZWes9Lqs7pQmCtwiOeUgztYBEeY0fuff8f/2cH/zCD4Jb58Zp1HOlEFAL9IrWgiwBblZsM=; 24:nHrOgL3Aglr43EgkjWUyS7ODGtF5Y6NfmnGn4s1ghdB5F6l48GfKk2M20LUbJ0ukkHxCVl9H9MIeu5/SOulvxQ2soojbfclnwEoQ87hT50A= SpamDiagnosticOutput: 1:99 SpamDiagnosticMetadata: NSPM X-Microsoft-Exchange-Diagnostics: 1; VI1PR0402MB2782; 7:WmkjcKWxMf6YWB6oYkvKICRSNb2yesCdQKamz1J5hWTAHkX6iavJW08iTAEJdnzu8aS/gvLaiDU/eyC5H3NDCMK7aAHKfa353RPiRjw9kHoKbS7befiQ6KxH7l301a4MxVKXfS4q0+7qVWTemg58tY/3Xm1Uva5ISRNShAqRZe5Os0wVdJj/tlPb7L7Ct/OHStcp7X+xgGH25/QOQExEvy0x5Hc7muvgKSp3lj69l60UhQ0k3pmnwWMuSr/10fgS X-MS-Office365-Filtering-Correlation-Id: 271fd7a4-f90e-4699-9d0c-08d5c2382939 X-OriginatorOrg: nxp.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 25 May 2018 12:07:59.8079 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 271fd7a4-f90e-4699-9d0c-08d5c2382939 X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 686ea1d3-bc2b-4c6f-a92c-d99c5c301635 X-MS-Exchange-Transport-CrossTenantHeadersStamped: VI1PR0402MB2782 Subject: [dpdk-dev] [PATCH] doc: move and update experimental API description X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 25 May 2018 12:08:02 -0000 Experimental API text has been moved into a sub-section of ABI Policy. A paragraph has been added to explain the process for removal of an experimental tag. Signed-off-by: Shreyansh Jain --- note: The movement of text into a sub-section is relevant as the previous position was in middle of a continuous text explaining ABI policy - whereas, experimental is not truly an ABI policy. No change to the original text has been made, except appending a new paragraph. Though, this does spoil the blame/praise. doc/guides/contributing/versioning.rst | 54 +++++++++++++++----------- 1 file changed, 31 insertions(+), 23 deletions(-) diff --git a/doc/guides/contributing/versioning.rst b/doc/guides/contributing/versioning.rst index c495294db..7127d39ee 100644 --- a/doc/guides/contributing/versioning.rst +++ b/doc/guides/contributing/versioning.rst @@ -43,29 +43,6 @@ ABI versions are set at the time of major release labeling, and the ABI may change multiple times, without warning, between the last release label and the HEAD label of the git tree. -APIs marked as ``experimental`` are not considered part of the ABI and may -change without warning at any time. Since changes to APIs are most likely -immediately after their introduction, as users begin to take advantage of -those new APIs and start finding issues with them, new DPDK APIs will be -automatically marked as ``experimental`` to allow for a period of stabilization -before they become part of a tracked ABI. - -Note that marking an API as experimental is a multi step process. -To mark an API as experimental, the symbols which are desired to be exported -must be placed in an EXPERIMENTAL version block in the corresponding libraries' -version map script. -Secondly, the corresponding definitions of those exported functions, and -their forward declarations (in the development header files), must be marked -with the ``__rte_experimental`` tag (see ``rte_compat.h``). -The DPDK build makefiles perform a check to ensure that the map file and the -C code reflect the same list of symbols. -This check can be circumvented by defining ``ALLOW_EXPERIMENTAL_API`` -during compilation in the corresponding library Makefile. - -In addition to tagging the code with ``__rte_experimental``, -the doxygen markup must also contain the EXPERIMENTAL string, -and the MAINTAINERS file should note the EXPERIMENTAL libraries. - ABI versions, once released, are available until such time as their deprecation has been noted in the Release Notes for at least one major release cycle. For example consider the case where the ABI for DPDK 2.0 has been @@ -119,6 +96,37 @@ readability purposes should be avoided. follow the relevant deprecation policy procedures as above: 3 acks and announcement at least one release in advance. +Experimental APIs +~~~~~~~~~~~~~~~~~ + +APIs marked as ``experimental`` are not considered part of the ABI and may +change without warning at any time. Since changes to APIs are most likely +immediately after their introduction, as users begin to take advantage of +those new APIs and start finding issues with them, new DPDK APIs will be +automatically marked as ``experimental`` to allow for a period of stabilization +before they become part of a tracked ABI. + +Note that marking an API as experimental is a multi step process. +To mark an API as experimental, the symbols which are desired to be exported +must be placed in an EXPERIMENTAL version block in the corresponding libraries' +version map script. +Secondly, the corresponding definitions of those exported functions, and +their forward declarations (in the development header files), must be marked +with the ``__rte_experimental`` tag (see ``rte_compat.h``). +The DPDK build makefiles perform a check to ensure that the map file and the +C code reflect the same list of symbols. +This check can be circumvented by defining ``ALLOW_EXPERIMENTAL_API`` +during compilation in the corresponding library Makefile. + +In addition to tagging the code with ``__rte_experimental``, +the doxygen markup must also contain the EXPERIMENTAL string, +and the MAINTAINERS file should note the EXPERIMENTAL libraries. + +For removing the experimental tag associated with an API, deprecation notice +is not required. Though, an API should remain in experimental state for at least +one release. Thereafter, normal process of posting patch for review to mailing +list can be followed. + Examples of Deprecation Notices ------------------------------- -- 2.17.0