Add text defining the release procedure and release numbering. Signed-off-by: Mike Holmes <[email protected]> --- release.dox | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 release.dox
diff --git a/release.dox b/release.dox new file mode 100644 index 0000000..7cde777 --- /dev/null +++ b/release.dox @@ -0,0 +1,70 @@ +/* Copyright (c) 2014, Linaro Limited + * All rights reserved + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** +@page release Release Management +The odp.git repo contains the API which is of primary concern when addressing the release numbering, the linux-generic implementation is not the focus of the release. + +@section release_numbering Release Numbering (ODP-<generation>.<major>.<minor>) + +The API uses a three digit release number, for ODP this number refers to +- The API header definitions +- The reference implementation (linux-generic) +- The documentation +- The API test & validation suite that certifies each of the above. + +@image html ODP_versioning.png "Version history diagram" width=\textwidth +@image latex ODP_versioning.eps "Version histroy diagram" width=\textwidth + + +The ODP API generation.major version will only change at well-defined release points. +An API release will be tagged @code ODP-<generation>.<major>.<minor> @endcode and bug fix releases on the platform will be tagged @code ODP-<generation>.<major>.<minor>-<sub> @endcode +No release will ever be made without incrementing the release number, the change will be according to the following guidelines. +Every change in API version will require a recompilation, relinking will not be sufficient. +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. + +@subsection generation (ODP-<generation>) +The ODP generation is intended to be a very slow moving digit that will only increment on very significant changes the ODP API is structured. +A change to this digit indicates a break in backwards compatibility. + +@subsection major (ODP-<generation>.<major>) +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 elements added to an enum that is an output from ODP. + +@subsection minor (ODP-<generation>.<major>.<minor>) +The minor digit is for changes that are backwards compatible. +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 on such that the old API remains. +- New element to an enum that is an input to ODP + +@subsection sub (ODP-<generation>.<major>.<minor>-<sub>) +The sub digit is used for backward compatible changes +The sub number is implementation driven. +Any existing app should work as before with the caveat that a bug fix may change the executable behavior (hopefully improve it) +- Optimize the implementation +- Documentation updates that do not affect the API +- bug fixes in implementation + +@section point_release Point Release Schedule +Point releases will be made throughout the year, a lose target is once per quarter depending on the feature load. +For example a release 1.1.0 that is made will regularly have support until the next point release is made at which time support for 1.1.0 would be dropped. + +@section lts Long Term Stable (LTS) +Long term stable release will be retroactively be selected from the point releases already made. +The determination will be made by the ODP steering committee (SC). +The duration of support will be decided by the SC. + +*/ -- 1.9.1 _______________________________________________ lng-odp mailing list [email protected] http://lists.linaro.org/mailman/listinfo/lng-odp
