From patchwork Wed Jun 3 17:23:27 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mike Holmes X-Patchwork-Id: 49493 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-lb0-f200.google.com (mail-lb0-f200.google.com [209.85.217.200]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id AD5EF20DDC for ; Wed, 3 Jun 2015 17:23:49 +0000 (UTC) Received: by lbcak1 with SMTP id ak1sf4378781lbc.2 for ; Wed, 03 Jun 2015 10:23:48 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:delivered-to:delivered-to:from:to:date :message-id:subject:precedence:list-id:list-unsubscribe:list-archive :list-post:list-help:list-subscribe:mime-version:content-type :content-transfer-encoding:errors-to:sender:x-original-sender :x-original-authentication-results:mailing-list; bh=T/ZeigEHzkzN/9yqWlddbrN//SrAENQ+AhfVMEBJ7sw=; b=I17f/KT0Jcav5wdWuJkUOoKW8FuRo+CWC0LNFAPW72jzgjOX5dF+OCW1IwOPeRY4Dg TmBi1WOrVJ56Ifh2B50ZkvyOFdV+CTsOrwz3J0js3rRbDnFHfbr5XRh9iHzN1fuLRgoT wSoVflm/XHwntpj7BXrlbN7gGHoUy+VBanGW/pyRq+5WnjlOxE9gB07tj5fBakak3U8+ LZ4y/tPGomev8up/ttMRaSoEwD6GmSOS9B/IPzkPy+DDolcU8vQ9wwKfFjfjG9Wjvg3q 0mXuF/iUHYM/KoWMrFnozX8Nxaifv2i58DcdMTardQ2Sl+IkDPIuOaVKfabqOAnNxQV+ l2/g== X-Gm-Message-State: ALoCoQkomIO1pCL+wifDLz7ujLtLSeRk3/UI4Fo+mgRRbZLp50cZx17Ri/xglryP+o844Mpy1xpO X-Received: by 10.112.13.200 with SMTP id j8mr31389771lbc.14.1433352228225; Wed, 03 Jun 2015 10:23:48 -0700 (PDT) X-BeenThere: patchwork-forward@linaro.org Received: by 10.152.25.166 with SMTP id d6ls97489lag.54.gmail; Wed, 03 Jun 2015 10:23:48 -0700 (PDT) X-Received: by 10.112.158.200 with SMTP id ww8mr9193749lbb.31.1433352228055; Wed, 03 Jun 2015 10:23:48 -0700 (PDT) Received: from mail-la0-f53.google.com (mail-la0-f53.google.com. [209.85.215.53]) by mx.google.com with ESMTPS id zn4si18538935lbb.103.2015.06.03.10.23.47 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 03 Jun 2015 10:23:48 -0700 (PDT) Received-SPF: pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.215.53 as permitted sender) client-ip=209.85.215.53; Received: by laei3 with SMTP id i3so13566372lae.3 for ; Wed, 03 Jun 2015 10:23:47 -0700 (PDT) X-Received: by 10.152.36.161 with SMTP id r1mr33148164laj.88.1433352227890; Wed, 03 Jun 2015 10:23:47 -0700 (PDT) X-Forwarded-To: patchwork-forward@linaro.org X-Forwarded-For: patch@linaro.org patchwork-forward@linaro.org Delivered-To: patch@linaro.org Received: by 10.112.108.230 with SMTP id hn6csp4023829lbb; Wed, 3 Jun 2015 10:23:46 -0700 (PDT) X-Received: by 10.140.236.77 with SMTP id h74mr38596633qhc.21.1433352225811; Wed, 03 Jun 2015 10:23:45 -0700 (PDT) Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id s68si1238595qgs.69.2015.06.03.10.23.44; Wed, 03 Jun 2015 10:23:45 -0700 (PDT) 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; Received: by lists.linaro.org (Postfix, from userid 109) id 1663261FB7; Wed, 3 Jun 2015 17:23:44 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on ip-10-142-244-252.ec2.internal X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_BLOCKED, RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL, URIBL_BLOCKED autolearn=disabled version=3.4.0 Received: from ip-10-142-244-252.ec2.internal (localhost [127.0.0.1]) by lists.linaro.org (Postfix) with ESMTP id 1965D61F75; Wed, 3 Jun 2015 17:23:39 +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 D3EDE61FA4; Wed, 3 Jun 2015 17:23:36 +0000 (UTC) Received: from mail-vn0-f51.google.com (mail-vn0-f51.google.com [209.85.216.51]) by lists.linaro.org (Postfix) with ESMTPS id DE1D461F71 for ; Wed, 3 Jun 2015 17:23:35 +0000 (UTC) Received: by vnbf129 with SMTP id f129so1998846vnb.10 for ; Wed, 03 Jun 2015 10:23:35 -0700 (PDT) X-Received: by 10.52.100.103 with SMTP id ex7mr44932354vdb.71.1433352215539; Wed, 03 Jun 2015 10:23:35 -0700 (PDT) Received: from mike-desktop.?.holmesfamily.ws (c-98-221-136-245.hsd1.nj.comcast.net. [98.221.136.245]) by mx.google.com with ESMTPSA id m1sm1476778vdm.5.2015.06.03.10.23.34 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Wed, 03 Jun 2015 10:23:34 -0700 (PDT) From: Mike Holmes To: petri.savolainen@linaro.org, bill.fischofer@linaro.org, lng-odp@lists.linaro.org Date: Wed, 3 Jun 2015 13:23:27 -0400 Message-Id: <1433352207-27965-1-git-send-email-mike.holmes@linaro.org> X-Mailer: git-send-email 2.1.4 X-Topics: patch Subject: [lng-odp] [PATCH] doc: doxygen: improve release management description X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: 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" X-Removed-Original-Auth: Dkim didn't pass. X-Original-Sender: mike.holmes@linaro.org X-Original-Authentication-Results: mx.google.com; spf=pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.215.53 as permitted sender) smtp.mail=patch+caf_=patchwork-forward=linaro.org@linaro.org Mailing-list: list patchwork-forward@linaro.org; contact patchwork-forward+owners@linaro.org X-Google-Group-Id: 836684582541 Signed-off-by: Mike Holmes --- doc/odp.dox | 7 ------- doc/release.dox | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 65 insertions(+), 7 deletions(-) create mode 100644 doc/release.dox diff --git a/doc/odp.dox b/doc/odp.dox index f574e21..0a3bc73 100644 --- a/doc/odp.dox +++ b/doc/odp.dox @@ -35,13 +35,6 @@ * of ODP, linux-generic is designed to provide best-in-class performance * for general Linux data plane support. * - * @section ODP Releases - * - * ODP releases follow a standard three-level naming designation. - * Changes to the API are reflected in the #ODP_VERSION_API_GENERATION - * and #ODP_VERSION_API_MAJOR numbers. A change to the #ODP_VERSION_API_MINOR - * number is used only for updates not breaking the API compatibility. - * * @section contact Contact Details * - The main web site is http://www.opendataplane.org/ * - The git repo is https://git.linaro.org/lng/odp.git diff --git a/doc/release.dox b/doc/release.dox new file mode 100644 index 0000000..bfdec14 --- /dev/null +++ b/doc/release.dox @@ -0,0 +1,65 @@ +/* Copyright (c) 2015, Linaro Limited + * All rights reserved + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** +@page release Release Management +@tableofcontents +@section api_numbering API Numbering + +The API uses a three digit release number, for ODP this number refers to +- The API header definitions +- The documentation + +ODP API releases follow a standard three-level naming designation. +Changes to the API are reflected in the #ODP_VERSION_API_GENERATION and #ODP_VERSION_API_MAJOR numbers. +A change to the #ODP_VERSION_API_MINOR number is used only for updates not breaking the API compatibility but which do touch the API source files in the include directory. + +The header file odp_version.h contains helper macros for dealing with ODP versions in application code. + +@note The version refers to API source compatibility and not binary compatibility. +Every change in API version will require a recompilation, relinking will not be sufficient. + +The ODP API generation & major version will only change at well-defined release points. +A release will be tagged @code v-. @endcode and bug fix releases will be tagged @code v-.. @endcode The first bug fix release minor = 1. + +The API odp_version_api_str() returns this string. + +@subsection generation Generation +The digit is the ODP API generation. +A change to this digit indicates a break in backwards compatibility. +@note The incompatibility covers the whole ODP API, however the change may be a tiny change to an esoteric function that is not used by a given application. + +- Altering API signature +- Altering a structure other than adding optional items at the end. +- Changing the required calling sequence for APIs +- Changes to the installed structure i.e. the output from "make install" moves a file in a way that breaks compilation. +- New element to an enum that is an output from ODP + +@subsection major Major +The digit is for changes that are likely backwards incompatible. +For example changes such as the addition of a new API. +Existing application code shall not have to change if the new API is not used. +- Adding a new struct +- Adding a new function +- Adding an additional alternate API to an existing one. +- New element to an enum that is an input to ODP + +@subsection minor Minor +The digit is used for backward compatible changes +Any existing app should work as before. +- Documentation updates + +@section implementation_string Implementation String + +The API odp_version_impl_str() returns a platform specific version string defined by the vendor. +The intent of this string is to provide a unique identifier of the service level or build number of the implementation. +Implementations should change this for each change they make (e.g., bug fix, performance improvement, etc.). +It is recommended that this be in a format suitable for logging for serviceability tracking. + +This affects +- The implementation +- In the case of linux-generic it also covers the test & validation suite. +*/