From patchwork Thu Jul 2 11:29:41 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mike Holmes X-Patchwork-Id: 50573 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-lb0-f199.google.com (mail-lb0-f199.google.com [209.85.217.199]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id 952BC218E1 for ; Thu, 2 Jul 2015 11:30:06 +0000 (UTC) Received: by lbbui3 with SMTP id ui3sf12565540lbb.2 for ; Thu, 02 Jul 2015 04:30:05 -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:cc: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=B7gkTnHZcpCij3wll34qItVaIW4Nf6aVOUqicMW0hZ0=; b=JRfFXpv7vCdEHBPJGMfEuVz4BfJ3TFqKnjR/RDUamK+sfX3X2mw7qnV9eA+oyqGHb6 pch8n08lEAwUpCqvmAY+vVL0qDUFGR37uNSEuwJDIsCdITER1KqZCZc10uHUV5pbH63s S83Eu1UMsCDeeIseLcURqhAFyuyV/q0yY9NSMB6a4w+WatbVXuBgVA40kdS/AQq8S7Z+ fVWZcFrPntSded6D98I9+zn1KZMo1u0wlebxai/LEyz+d0s8o9oZTVDqt2RZL15cJfCs ih5lIiseSUmrIDIHCxtiDZSxJfwBt+kcVsVw/1BAtqGDwcQlVsdWbJ6Xg5j0yIYWfb5p kLzQ== X-Gm-Message-State: ALoCoQkG4Q6SlR4DQdF6V5WnMUudnFfrj0dyAtRJBWbyHYLwM1GMn2+1sorNJW5EMNto3d7r2UfG X-Received: by 10.194.90.6 with SMTP id bs6mr8758162wjb.4.1435836605507; Thu, 02 Jul 2015 04:30:05 -0700 (PDT) X-BeenThere: patchwork-forward@linaro.org Received: by 10.152.207.2 with SMTP id ls2ls328344lac.51.gmail; Thu, 02 Jul 2015 04:30:04 -0700 (PDT) X-Received: by 10.112.122.9 with SMTP id lo9mr30161145lbb.104.1435836604954; Thu, 02 Jul 2015 04:30:04 -0700 (PDT) Received: from mail-la0-f49.google.com (mail-la0-f49.google.com. [209.85.215.49]) by mx.google.com with ESMTPS id t12si4208244lby.128.2015.07.02.04.30.04 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 02 Jul 2015 04:30:04 -0700 (PDT) Received-SPF: pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.215.49 as permitted sender) client-ip=209.85.215.49; Received: by lagh6 with SMTP id h6so58960243lag.2 for ; Thu, 02 Jul 2015 04:30:04 -0700 (PDT) X-Received: by 10.112.234.200 with SMTP id ug8mr29738140lbc.117.1435836604244; Thu, 02 Jul 2015 04:30:04 -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 hn6csp411058lbb; Thu, 2 Jul 2015 04:30:02 -0700 (PDT) X-Received: by 10.55.23.132 with SMTP id 4mr62754265qkx.72.1435836602365; Thu, 02 Jul 2015 04:30:02 -0700 (PDT) Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id 192si5976541qhv.0.2015.07.02.04.30.00; Thu, 02 Jul 2015 04:30:02 -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 4B03961DEF; Thu, 2 Jul 2015 11:30:00 +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=-2.6 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H2, 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 E255961D03; Thu, 2 Jul 2015 11:29:51 +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 4578961D2A; Thu, 2 Jul 2015 11:29:48 +0000 (UTC) Received: from mail-qk0-f172.google.com (mail-qk0-f172.google.com [209.85.220.172]) by lists.linaro.org (Postfix) with ESMTPS id 5C84361CC4 for ; Thu, 2 Jul 2015 11:29:47 +0000 (UTC) Received: by qkbp125 with SMTP id p125so49174910qkb.2 for ; Thu, 02 Jul 2015 04:29:47 -0700 (PDT) X-Received: by 10.140.236.147 with SMTP id h141mr43519309qhc.77.1435836587072; Thu, 02 Jul 2015 04:29:47 -0700 (PDT) Received: from localhost.localdomain (c-98-221-136-245.hsd1.nj.comcast.net. [98.221.136.245]) by mx.google.com with ESMTPSA id h133sm2556240qhc.46.2015.07.02.04.29.46 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Thu, 02 Jul 2015 04:29:46 -0700 (PDT) From: Mike Holmes To: maxim.uvarov@linaro.org Date: Thu, 2 Jul 2015 07:29:41 -0400 Message-Id: <1435836581-24870-1-git-send-email-mike.holmes@linaro.org> X-Mailer: git-send-email 2.1.4 X-Topics: patch Cc: lng-odp@lists.linaro.org Subject: [lng-odp] [PATCH v2] 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.49 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 Reviewed-by: Bill Fischofer --- v2 Dont put a period at the end of lists 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..eb6eca7 --- /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. +*/