On Thu, Jul 2, 2015 at 6:29 AM, Mike Holmes <mike.hol...@linaro.org> wrote:
> Signed-off-by: Mike Holmes <mike.hol...@linaro.org> > Reviewed-by: Bill Fischofer <bill.fischo...@linaro.org> > --- > 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-<generation>.<major> @endcode and bug > fix releases will be tagged @code v-<generation>.<major>.<minor> @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. > +*/ > -- > 2.1.4 > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > https://lists.linaro.org/mailman/listinfo/lng-odp >
_______________________________________________ lng-odp mailing list lng-odp@lists.linaro.org https://lists.linaro.org/mailman/listinfo/lng-odp