doc: doxygen: improve release management description

Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
---
 doc/odp.dox     |  7 -------
 doc/release.dox | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 65 insertions(+), 7 deletions(-)
 create mode 100644 doc/release.dox

Ping

On 3 June 2015 at 13:23, Mike Holmes <mike.holmes@linaro.org> wrote:

> Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
> ---
>  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-<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
>
>

Ping

As per the open call just now, we need to get support behind our efforts to
improve all documentation, patches like this fall on the floor.

Who cares about the docs that we can target as reviewers ?

On 12 June 2015 at 15:37, Mike Holmes <mike.holmes@linaro.org> wrote:

> Ping
>
> On 3 June 2015 at 13:23, Mike Holmes <mike.holmes@linaro.org> wrote:
>
>> Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
>> ---
>>  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-<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
>>
>>
>
>
> --
> Mike Holmes
> Technical Manager - Linaro Networking Group
> Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM SoCs
>
>
>

Mike, you a little bit clean up text. Few notes are bellow:

Thanks,
Maxim.

On 06/03/15 20:23, Mike Holmes wrote:
> Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
> ---
>   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.

versions.
> +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
Some lines have dots in the end, some not. Can we make it the same style.

> +
> +@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
same here.
> +
> +@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.
> +*/